In breve
- Per gli agenti che chiamano API per conto di un utente connesso, la risposta attuale di Entra è il flusso on-behalf-of (OBO); ID-JAG per ora è solo un sondaggio di interesse.
- La middle API si dimostra con un'asserzione firmata con certificato e non ha alcun client secret.
- Un solo accesso produce token separati per ogni audience: l'utente resta lo stesso e cambia l'applicazione chiamante.
- Uno scope senza consenso fallisce con AADSTS65001; conta il consenso sul service principal.
- I token OBO non conservano il client originale, quindi gli audit devono incrociare i log di accesso.
Ripeti questo lab
Ho scritto questo lab perché tu possa rifarlo per conto tuo. Ogni passo ha i comandi da copiare e l'output che ho ottenuto io, e puoi segnarlo come fatto. Le spunte restano solo nel tuo browser.
Copia un prompt già pronto per Claude Code, Cursor, Codex o un altro agente di codice. Solo per ambienti di test.
Mostra il prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Flusso on-behalf-of di Microsoft Entra per il tier intermedio di un agente: certificato, senza client secret Read the whole lab here (Markdown): https://iamops.dev/it/entra-on-behalf-of-agent-middle-tier.md What the lab needs before the first step: - A separate test tenant (Entra ID Free is enough) where you are Global Administrator - Never do this in a production tenant: OBO tokens carry real user claims - Values I have to set myself (the lab uses placeholders): <TENANT_ID>, <CLIENT_APP_ID>, <MIDDLE_API_APP_ID>, <RESOURCE_API_APP_ID> How I want you to work: 1. Read the lab from start to finish first (each step lists its own prerequisites). Then check that the prerequisites are in place and that the tool versions match what the lab expects. Tell me what is missing before you run anything. 2. Run one step at a time. Before each command, show it to me and say in a sentence what it does. 3. Ask me before anything that costs money, creates cloud resources, touches a real tenant or account, or deletes anything. Wait for my answer. 4. Use the placeholders from the lab. Never paste real secrets, tokens or production identities into a command, a file or this chat. If a value is needed, tell me where to set it myself. 5. After each step, compare the output with the expected output in the lab. If it does not match, stop and tell me what differs. Do not carry on or invent a fix without asking me. 6. At the end, report what passed, what failed and which cleanup you did. Then offer to tick the steps off for me. The lab page keeps ticks only in my browser, so if you cannot do that, list the steps I should tick. This lab is for test environments only. Do not run it against production, or against a tenant or account that holds real data or real users. You may answer in my language.
Il 14 novembre 2026 Microsoft ha aggiunto un articolo di Learn che per la prima volta nomina ID-JAG accanto a Microsoft Entra Agent ID e apre un modulo di interesse. È un sondaggio di prontezza, non una funzione rilasciata: oggi Entra non emette né accetta ID-JAG. Per gli agenti che devono chiamare API per conto di un utente connesso, la risposta attuale di Entra è il flusso on-behalf-of (OBO). L’ho eseguito dall’inizio alla fine in un tenant usa e getta e ho annotato cosa fa ogni passaggio.
Cosa mostra il laboratorio#
Tre registrazioni di app rappresentano un sistema di agenti:
| App | Ruolo | Credenziale |
|---|---|---|
| Client | L’interfaccia o la riga di comando dell’agente. Client pubblico, accesso con device code. | Nessuna |
| Agent Middle API | Il back end dell’agente. Esegue lo scambio OBO. | Un certificato X.509, zero client secret |
| Resource API | L’API a valle. Espone lo scope delegato Data.Read. |
n/d |
L’utente accede una sola volta al Client. Il Client detiene un token la cui audience è solo la middle API. La middle API lo scambia con un token per la Resource API e con un altro per Microsoft Graph, dimostrando chi è con un’asserzione firmata con certificato invece che con un segreto.
Configurazione#
Usate un tenant di prova separato (Entra ID Free basta, non servono risorse Azure). I token OBO contengono claim reali dell’utente, e un tenant usa e getta tiene gli esperimenti lontani da consenso, Conditional Access e log di audit di produzione. Nel portale:
- Registrate la Resource API ed esponete uno scope delegato
Data.Read(amministratori e utenti). - Registrate l’Agent Middle API, esponete
access_as_usere aggiungete i permessi delegatiData.Reade Microsoft GraphUser.Read, poi concedete il consenso amministratore. - Generate una chiave RSA a 2048 bit e un certificato autofirmato di 60 giorni con
openssl, tenete la chiave privata sulla macchina (modalità 0600) e caricate solo il certificato pubblico in Certificates & secrets. - Registrate il Client come client pubblico (redirect
http://localhost, Allow public client flows attivo) con il permesso peraccess_as_usereUser.Read.




L’esecuzione#
Accesso con device code. Il Client chiede un codice all’endpoint devicecode v2.0. La richiesta contiene solo l’ID del Client e lo scope della middle API, nessun segreto. L’utente inserisce il codice su un secondo dispositivo ed Entra mostra un controllo «approva l’accesso su un altro dispositivo» che indica app e posizione; l’utente deve approvarlo a mano.

Il token utente. Dopo l’approvazione il Client interroga l’endpoint dei token. Il suo token è inutilizzabile direttamente contro la Resource API o Graph, perché la sua audience è la middle API.

Lo scambio. La middle API costruisce un’asserzione del client (un JWT RS256 con l’impronta del certificato in x5t; emittente e soggetto sono il suo client ID; audience è l’endpoint dei token; dieci minuti di validità), la firma con la chiave privata e invia la richiesta OBO:
POST https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
client_id=<middle-api-id>
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<RS256 JWT with x5t in the header>
assertion=<the user token>
scope=api://<resource-api-id>/Data.Read
requested_token_use=on_behalf_of
La stessa asserzione con scope https://graph.microsoft.com/User.Read restituisce un token per Graph, che il laboratorio usa una volta per GET /v1.0/me.

Confronto dei tre token. L’utente non cambia mai. L’audience segue l’API chiamata e appid passa dal Client alla middle API.

Il test negativo. Chiedere https://graph.microsoft.com/Mail.Read, a cui nessuno ha dato il consenso, fallisce nel servizio dei token:

Insidie#
- Il client originale si perde. I token OBO v1 registrano solo l’ultima applicazione (
appid). Non c’è un claimactcome in un’implementazione RFC 8693, quindi per ricostruire la catena l’audit deve collegare i log di accesso. - L’audience in ingresso deve essere la middle API. Un token destinato a un’altra app viene rifiutato: è la protezione contro il confused deputy.
- Il device code richiede «Allow public client flows». È anche il flusso sfruttato dal device code phishing. La schermata «approva l’accesso su un altro dispositivo» è la contromisura di Microsoft; insegnate agli utenti a premere «Non sono stato io» e limitate il flusso con il Conditional Access dove gli agenti non ne hanno bisogno.
- Conta il consenso amministratore sul service principal, non ciò che elenca la registrazione.
Indicazioni di sicurezza#
- Usate un certificato o una credenziale federata per il livello intermedio. Nessun segreto significa nulla di riutilizzabile da far trapelare da configurazioni, variabili di CI o log.
- Tenete minimi gli scope delegati del livello intermedio e rivedeteli sul service principal.
- Lasciate il Client senza credenziali. Potrà sempre e solo detenere il token dell’utente per la middle API, mai un token a valle.
- Pianificate il collegamento per l’audit (utente, agente, audience a valle), perché i token OBO non conservano il primo passaggio.
- Annotate quale concessione usa ogni passaggio (OBO oggi; ID-JAG quando Entra lo supporterà) e dove risiede il consenso, così le revisioni degli accessi vedono le concessioni dei service principal.
Cosa non è stato eseguito#
Non sono stati eseguiti i blueprint e le identità di agente di Entra Agent ID (lo stesso laboratorio con permessi ereditabili). Non è stata testata la policy di Conditional Access che blocca il device code. Le attività aggiuntive (rimuovere il consenso e ripetere lo scambio, claim opzionali, token v2) non sono state eseguite. Gli screenshot del portale sono ritagliati sul contenuto della pagina: barra del browser, menu del profilo e tutti gli identificatori di tenant, applicazioni e utenti sono rimossi. Per questo laboratorio non viene pubblicata alcuna registrazione.
Le immagini del terminale sono state generate dall’output salvato dell’esecuzione, con gli identificatori sostituiti da segnaposto. Gli screenshot del portale mostrano solo il contenuto della pagina.
Ripeti questo lab#
Per questo lab serve un tenant Entra usa e getta, openssl, curl, jq e Python 3, senza altre librerie. Conta circa 60 minuti, la maggior parte per cliccare una volta nel portale. Apri ogni passo, copia i blocchi e confronta l'output con il mio.
Ogni valore tra parentesi angolari è un segnaposto per il tuo ambiente di test. Nulla in questa pagina è un identificativo o un segreto reale.
Imposta le variabili una sola volta
# Paste into every terminal you use for this lab. Replace each <PLACEHOLDER> with the value from your own test tenant.
export TENANT_ID='<TENANT_ID>'
export CLIENT_ID='<CLIENT_APP_ID>' # the public client (the agent's UI)
export MIDDLE_ID='<MIDDLE_API_APP_ID>' # the agent's middle API
export RESOURCE_ID='<RESOURCE_API_APP_ID>' # the downstream Resource API
export AUTHORITY="https://login.microsoftonline.com/$TENANT_ID"
export KEY_FILE="middle-api.key"
export CERT_FILE="middle-api.pem" 0 di 6 passi fatti
Passo 1Registra le tre app in un tenant di prova
Obiettivo. Crea la Resource API, la Agent Middle API e il Client. Solo la API intermedia riceve una credenziale, ed è un certificato.
Prerequisiti
- Un tenant di prova separato (basta Entra ID Free) di cui sei Global Administrator
- Non farlo mai in un tenant di produzione: i token OBO contengono claim reali dell'utente
Resource API
Entra admin center > App registrations > New registration, single tenant.
Expose an API > Application ID URI: api://<RESOURCE_API_APP_ID>
Add a scope: Data.Read (admins and users can consent).
Agent Middle API
New registration, single tenant.
Expose an API > Application ID URI: api://<MIDDLE_API_APP_ID>, scope access_as_user.
API permissions > Add: your Resource API / Data.Read (delegated) and Microsoft Graph / User.Read (delegated).
Grant admin consent for the tenant.
Certificates & secrets: leave the Client secrets tab empty (0 secrets). The certificate comes in the next step.
Client
New registration, single tenant, redirect URI (public client): http://localhost
Authentication > Allow public client flows: Yes.
API permissions > Add: Agent Middle API / access_as_user and Microsoft Graph / User.Read (delegated).
Copy the three Application (client) IDs and the Directory (tenant) ID into env.sh. Output atteso
Three app registrations, each with an Application (client) ID.
Agent Middle API > Certificates & secrets > Client secrets: 0
Agent Middle API > API permissions: Data.Read and User.Read, both "Granted for <tenant name>" Passo 2Crea il certificato della API intermedia
Obiettivo. Crea una chiave a 2048 bit e un certificato autofirmato di 60 giorni. La chiave privata resta su questa macchina; a Entra va solo il certificato pubblico.
Prerequisiti
- openssl 1.1 o successivo
- env.sh caricato in questo terminale
umask 077
openssl req -x509 -newkey rsa:2048 -nodes -keyout "$KEY_FILE" -out "$CERT_FILE" -days 60 -subj "/CN=agent-middle-api"
openssl x509 -in "$CERT_FILE" -outform DER -out middle-api.cer
openssl x509 -in "$CERT_FILE" -noout -subject -startdate -enddate -fingerprint -sha1 # Upload only the public part: middle-api.cer
# Agent Middle API > Certificates & secrets > Certificates > Upload certificate.
# The private key ($KEY_FILE) never leaves this machine. Output atteso
subject=CN = agent-middle-api
notBefore=<start-date>
notAfter=<end-date>
sha1 Fingerprint=<certificate-thumbprint> Passo 3Fai accedere l'utente con il device code
Obiettivo. Il Client chiede un device code solo con il proprio ID e lo scope della API intermedia. Approvi l'accesso in un browser su un altro dispositivo e lo script aspetta.
Prerequisiti
- Per il Client è attivo Allow public client flows
- Un utente di prova nel tenant che possa accedere
curl -s "$AUTHORITY/oauth2/v2.0/devicecode" \
-d client_id="$CLIENT_ID" \
-d scope="api://$MIDDLE_ID/access_as_user openid profile offline_access" > devicecode.json
jq '{verification_uri, expires_in, interval, message}' devicecode.json #!/usr/bin/env bash
# Poll the token endpoint every 5 seconds until you have approved the sign-in in the browser.
DC=$(jq -r .device_code devicecode.json)
for i in $(seq 1 170); do
curl -s -X POST "$AUTHORITY/oauth2/v2.0/token" -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
-d client_id="$CLIENT_ID" -d device_code="$DC" > user_token.json
if grep -q access_token user_token.json; then echo GOT; exit 0; fi
grep -q authorization_pending user_token.json || { jq . user_token.json; exit 1; }
sleep 5
done chmod +x poll.sh && ./poll.sh # now open the verification URI, enter the code and approve Output atteso
{
"verification_uri": "https://login.microsoft.com/device",
"expires_in": 900,
"interval": 5,
"message": "To sign in, use a web browser to open https://login.microsoft.com/device and enter the code <user-code> to authenticate."
}
GOT Passo 4Scambia il token per conto dell'utente
Obiettivo. La API intermedia firma un client assertion con il certificato e scambia il token dell'utente con uno per la Resource API e uno per Microsoft Graph.
Prerequisiti
- user_token.json del passo precedente e il certificato caricato sulla API intermedia
- Python 3.9 o successivo; nessun pacchetto da installare
"""On-behalf-of exchange with a certificate-signed client assertion. Standard library plus openssl only."""
import base64, hashlib, json, os, subprocess, time, urllib.error, urllib.parse, urllib.request, uuid
TENANT, MIDDLE, RESOURCE = os.environ["TENANT_ID"], os.environ["MIDDLE_ID"], os.environ["RESOURCE_ID"]
KEY, PEM = os.environ["KEY_FILE"], os.environ["CERT_FILE"]
b64 = lambda b: base64.urlsafe_b64encode(b).rstrip(b"=").decode()
der = subprocess.check_output(["openssl", "x509", "-in", PEM, "-outform", "DER"])
x5t = b64(hashlib.sha1(der).digest()) # certificate thumbprint for the JWT header
token_endpoint = f"https://login.microsoftonline.com/{TENANT}/oauth2/v2.0/token"
now = int(time.time())
header = {"alg": "RS256", "typ": "JWT", "x5t": x5t}
payload = {"aud": token_endpoint, "iss": MIDDLE, "sub": MIDDLE, "jti": str(uuid.uuid4()), "nbf": now, "exp": now + 600}
signing_input = (b64(json.dumps(header).encode()) + "." + b64(json.dumps(payload).encode())).encode()
signature = subprocess.run(["openssl", "dgst", "-sha256", "-sign", KEY], input=signing_input, capture_output=True, check=True).stdout
assertion = signing_input.decode() + "." + b64(signature)
user_token = json.load(open("user_token.json"))["access_token"]
def obo(scope):
data = urllib.parse.urlencode({
"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "client_id": MIDDLE,
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer", "client_assertion": assertion,
"assertion": user_token, "scope": scope, "requested_token_use": "on_behalf_of"}).encode()
try:
return json.load(urllib.request.urlopen(token_endpoint, data))
except urllib.error.HTTPError as e:
return json.load(e)
def claims(token):
part = token.split(".")[1]
return json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
keep = ["aud", "iss", "appid", "azp", "scp", "roles", "oid", "upn", "preferred_username", "name", "tid", "ver", "idtyp", "exp", "iat"]
show = lambda c: {k: c[k] for k in keep if k in c}
out = {"step1_user_token_for_middle_api": show(claims(user_token))}
r = obo(f"api://{RESOURCE}/Data.Read")
out["step2_obo_for_resource_api"] = show(claims(r["access_token"])) if "access_token" in r else r
g = obo("https://graph.microsoft.com/User.Read")
out["step3_obo_for_graph"] = show(claims(g["access_token"])) if "access_token" in g else {k: g.get(k) for k in ("error", "error_description")}
if "access_token" in g:
req = urllib.request.Request("https://graph.microsoft.com/v1.0/me?$select=displayName,userPrincipalName",
headers={"Authorization": "Bearer " + g["access_token"]})
out["step4_graph_me"] = json.load(urllib.request.urlopen(req))
# negative test: a scope the middle API has no consent for
n = obo("https://graph.microsoft.com/Mail.Read")
out["step5_negative_mail_read"] = {k: (n.get(k) or "")[:300] for k in ("error", "error_description")} if "access_token" not in n else {"unexpected": "token issued"}
print(json.dumps(out, indent=2)) python3 obo.py > obo_result.json
jq '.step2_obo_for_resource_api, .step3_obo_for_graph, .step4_graph_me' obo_result.json Output atteso
{
"iss": "https://sts.windows.net/<tenant-id>/",
"aud": "api://<resource-api-id>",
"appid": "<middle-api-id>",
"scp": "Data.Read",
"oid": "<user-object-id>",
"name": "<user-display-name>",
"tid": "<tenant-id>",
"ver": "1.0"
}
{
"aud": "https://graph.microsoft.com",
"iss": "https://sts.windows.net/<tenant-id>/",
"appid": "<middle-api-id>",
"scp": "User.Read profile openid email",
"oid": "<user-object-id>",
"name": "<user-display-name>",
"tid": "<tenant-id>",
"idtyp": "user"
}
{
"displayName": "<user-display-name>",
"userPrincipalName": "<user-principal-name>"
} Passo 5Confronta i token e chiedi uno scope senza consenso
Obiettivo. Leggi i tre token fianco a fianco, poi guarda l'errore AADSTS65001 per Mail.Read.
Prerequisiti
- obo_result.json del passo precedente
- column (da util-linux o bsdmainutils) per la tabella
jq '.step5_negative_mail_read' obo_result.json
echo "--- claims across the three tokens"
jq -r '[.step1_user_token_for_middle_api, .step2_obo_for_resource_api, .step3_obo_for_graph]
| (["claim","user token","OBO resource","OBO graph"] | @tsv),
(["aud","appid","scp","oid","tid"] as $ks | $ks[] as $k | [$k] + map(.[$k] // "-") | @tsv)' obo_result.json | column -t -s$'\t' Output atteso
{
"error": "invalid_grant",
"error_description": "AADSTS65001: The user or administrator has not consented to use the application with ID '<middle-api-id>' named '<middle-api-name>'. Send an interactive authorization request for this user and resource. Trace ID: <trace-id> Correlation ID: <correlation-id>"
}
--- claims across the three tokens
claim user token OBO resource OBO graph
aud api://<middle-api-id> api://<resource-api-id> https://graph.microsoft.com
appid <client-app-id> <middle-api-id> <middle-api-id>
scp access_as_user Data.Read User.Read profile openid email
oid <user-object-id> <user-object-id> <user-object-id>
tid <tenant-id> <tenant-id> <tenant-id> Passo 6Pulizia
Obiettivo. Elimina la chiave, il certificato, i file dei token e le registrazioni delle app.
Prerequisiti
- Sei nella directory in cui hai eseguito il lab
rm -f "$KEY_FILE" "$CERT_FILE" middle-api.cer devicecode.json user_token.json obo.py obo_result.json poll.sh
ls "$KEY_FILE" 2>&1 # check: the key is gone
unset TENANT_ID CLIENT_ID MIDDLE_ID RESOURCE_ID
# Portal: delete the three app registrations (App registrations > select > Delete),
# or delete the whole test tenant if you created it just for this lab. Output atteso
ls: cannot access 'middle-api.key': No such file or directory Fonti#
- Microsoft Learn: OAuth 2.0 on-behalf-of flow
- Microsoft Learn, 14 Nov 2026: Understand agent SSO, provisioning, and authorization (Microsoft Entra Agent ID)
- Entra.News Daily, 14 Nov 2026: documentation change for the same article
- Microsoft Learn: Microsoft identity platform and the OAuth 2.0 device authorization grant
- RFC 8693: OAuth 2.0 Token Exchange
Discuti questo articolo#
Ti è stato utile? Condividilo e dimmi cosa ne pensi.
Questo articolo in formato Markdown · RSS · JSON feed
Nuovi articoli via email
Una email a settimana con nuovi articoli e lab. Disiscrizione in qualsiasi momento.
Il tuo indirizzo è salvato su Kit, il servizio che invia le email. Dettagli