En resumen
- Para los agentes que llaman a API en nombre de un usuario con sesión iniciada, la respuesta actual de Entra es el flujo on-behalf-of (OBO); ID-JAG es hoy solo una encuesta de disponibilidad.
- La middle API se identifica con una aserción firmada con certificado y no guarda ningún secreto de cliente.
- Un inicio de sesión produce tokens distintos por audiencia: el usuario sigue siendo el mismo y cambia la aplicación que llama.
- Un scope sin consentimiento falla con AADSTS65001; lo que cuenta es el consentimiento en el service principal.
- Los tokens OBO no conservan el cliente original, así que las auditorías deben cruzar los registros de inicio de sesión.
Repite este lab
Escribí este lab para que puedas repetirlo tú mismo. Cada paso tiene los comandos para copiar y la salida que obtuve yo, y puedes marcarlo como hecho. Las marcas se quedan solo en este navegador.
Copia un prompt listo para Claude Code, Cursor, Codex o cualquier agente de código. Solo para entornos de prueba.
Mostrar el prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Flujo on-behalf-of de Microsoft Entra para la capa intermedia de un agente: certificado, sin secretos Read the whole lab here (Markdown): https://iamops.dev/es/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.
El 14 de noviembre de 2026 Microsoft añadió un artículo de Learn que por primera vez nombra ID-JAG junto a Microsoft Entra Agent ID y abre un formulario de interés. Es una encuesta de disponibilidad, no una función lanzada: hoy Entra ni emite ni acepta ID-JAG. Para los agentes que deben llamar a API por un usuario con sesión iniciada, la respuesta actual de Entra es el flujo on-behalf-of (OBO). Lo ejecuté de principio a fin en un tenant desechable y anoté qué hace cada paso.
Qué muestra el laboratorio#
Tres registros de aplicación representan un sistema de agentes:
| Aplicación | Función | Credencial |
|---|---|---|
| Client | La interfaz o la línea de comandos del agente. Cliente público, inicio de sesión con device code. | Ninguna |
| Agent Middle API | El back end del agente. Realiza el intercambio OBO. | Un certificado X.509, cero secretos de cliente |
| Resource API | La API posterior. Expone el scope delegado Data.Read. |
n/a |
El usuario inicia sesión una vez en el Client. El Client guarda un token cuya audiencia es solo la middle API. La middle API lo intercambia por un token para la Resource API y otro para Microsoft Graph, demostrando quién es con una aserción firmada con certificado en lugar de un secreto.
Preparación#
Use un tenant de prueba aparte (basta Entra ID Free, no se necesitan recursos de Azure). Los tokens OBO llevan claims reales del usuario, y un tenant desechable mantiene los experimentos lejos del consentimiento, el acceso condicional y los registros de auditoría de producción. En el portal:
- Registre la Resource API y exponga un scope delegado
Data.Read(administradores y usuarios). - Registre la Agent Middle API, exponga
access_as_usery añada los permisos delegadosData.Ready Microsoft GraphUser.Read; después conceda el consentimiento de administrador. - Genere con
openssluna clave RSA de 2048 bits y un certificado autofirmado de 60 días, deje la clave privada en la máquina (modo 0600) y suba solo el certificado público en Certificates & secrets. - Registre el Client como cliente público (redirección
http://localhost, Allow public client flows activado) con permiso paraaccess_as_useryUser.Read.




La ejecución#
Inicio de sesión con device code. El Client pide un código al endpoint devicecode v2.0. La petición lleva solo el ID del Client y el scope de la middle API, ningún secreto. El usuario introduce el código en un segundo dispositivo y Entra muestra una comprobación «aprobar el inicio de sesión en otro dispositivo» que nombra la app y la ubicación; el usuario debe aprobarla a mano.

El token de usuario. Tras la aprobación, el Client consulta el endpoint de tokens. Su token no sirve directamente contra la Resource API ni contra Graph, porque su audiencia es la middle API.

El intercambio. La middle API construye una aserción de cliente (un JWT RS256 con la huella del certificado en x5t; emisor y sujeto son su propio ID de cliente; audiencia, el endpoint de tokens; diez minutos de vida), la firma con la clave privada y envía la petición 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 misma aserción con el scope https://graph.microsoft.com/User.Read devuelve un token de Graph, que el laboratorio usa una vez para GET /v1.0/me.

Comparar los tres tokens. El usuario nunca cambia. La audiencia sigue a la API que se llama y appid pasa del Client a la middle API.

La prueba negativa. Pedir https://graph.microsoft.com/Mail.Read, que nadie ha consentido, falla en el servicio de tokens:

Trampas habituales#
- Se pierde el cliente original. Los tokens OBO v1 solo registran la última aplicación (
appid). No hay claimactcomo en una implementación de RFC 8693, así que una auditoría debe cruzar los registros de inicio de sesión para reconstruir la cadena. - La audiencia de entrada debe ser la middle API. Un token dirigido a otra app se rechaza: es la protección contra el confused deputy.
- Device code exige «Allow public client flows». Es también el flujo que explota el device code phishing. La pantalla «aprobar el inicio de sesión en otro dispositivo» es la mitigación de Microsoft; enseñe a los usuarios a pulsar «No fui yo» y restrinja el flujo con acceso condicional donde los agentes no lo necesiten.
- Cuenta el consentimiento de administrador en el service principal, no lo que enumera el registro.
Conclusiones de seguridad#
- Use un certificado o una credencial federada para la capa intermedia. Sin secreto no hay nada reutilizable que pueda filtrarse de la configuración, las variables de CI o los registros.
- Mantenga mínimos los scopes delegados de la capa intermedia y revíselos en el service principal.
- Deje el Client sin credenciales. Solo podrá guardar el token del usuario para la middle API, nunca un token posterior.
- Planifique el cruce de datos de auditoría (usuario, agente, audiencia posterior), porque los tokens OBO no conservan el primer salto.
- Anote qué concesión usa cada salto (OBO hoy; ID-JAG cuando Entra lo admita) y dónde reside el consentimiento, para que las revisiones de acceso vean las concesiones de los service principals.
Qué no se ejecutó#
No se ejecutaron los blueprints ni las identidades de agente de Entra Agent ID (el mismo laboratorio con permisos heredables). No se probó la directiva de acceso condicional que bloquea device code. Las tareas adicionales (retirar el consentimiento y repetir el intercambio, claims opcionales, tokens v2) no se ejecutaron. Las capturas del portal están recortadas al contenido de la página: se eliminaron la barra del navegador, el menú de perfil y todos los identificadores de tenant, aplicaciones y usuarios. Para este laboratorio no se publica ninguna grabación.
Las imágenes del terminal se generaron a partir de la salida guardada de la ejecución, con los identificadores sustituidos por marcadores. Las capturas del portal muestran solo el contenido de la página.
Repite este lab#
Este lab necesita un tenant de Entra desechable, openssl, curl, jq y Python 3, sin nada más. Cuenta con unos 60 minutos, casi todos para recorrer el portal una vez. Abre cada paso, copia los bloques y compara la salida con la mía.
Cada valor entre corchetes angulares es un marcador para tu entorno de prueba. Nada en esta página es un identificador o secreto real.
Define tus variables una sola vez
# 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 de 6 pasos hechos
Paso 1Registra las tres aplicaciones en un tenant de prueba
Objetivo. Crea la Resource API, la Agent Middle API y el Client. Solo la API intermedia recibe una credencial, y es un certificado.
Requisitos
- Un tenant de prueba aparte (basta Entra ID Free) donde seas Global Administrator
- No lo hagas nunca en un tenant de producción: los tokens OBO llevan claims reales del usuario
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. Salida esperada
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>" Paso 2Crea el certificado de la API intermedia
Objetivo. Crea una clave de 2048 bits y un certificado autofirmado de 60 días. La clave privada se queda en esta máquina; a Entra solo va el certificado público.
Requisitos
- openssl 1.1 o posterior
- env.sh cargado en esta terminal
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. Salida esperada
subject=CN = agent-middle-api
notBefore=<start-date>
notAfter=<end-date>
sha1 Fingerprint=<certificate-thumbprint> Paso 3Inicia sesión del usuario con device code
Objetivo. El Client pide un device code solo con su ID y el scope de la API intermedia. Apruebas el inicio de sesión en un navegador de otro dispositivo y el script espera.
Requisitos
- En el Client está activado Allow public client flows
- Un usuario de prueba del tenant que pueda iniciar sesión
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 Salida esperada
{
"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 Paso 4Intercambia el token en nombre del usuario
Objetivo. La API intermedia firma una client assertion con el certificado y cambia el token del usuario por uno para la Resource API y otro para Microsoft Graph.
Requisitos
- user_token.json del paso anterior y el certificado subido a la API intermedia
- Python 3.9 o posterior; no hay paquetes que instalar
"""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 Salida esperada
{
"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>"
} Paso 5Compara los tokens y pide un scope sin consentimiento
Objetivo. Lee los tres tokens uno al lado del otro y mira después el error AADSTS65001 de Mail.Read.
Requisitos
- obo_result.json del paso anterior
- column (de util-linux o bsdmainutils) para la tabla
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' Salida esperada
{
"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> Paso 6Limpieza
Objetivo. Borra la clave, el certificado, los archivos de tokens y los registros de aplicaciones.
Requisitos
- Estás en el directorio donde ejecutaste el 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. Salida esperada
ls: cannot access 'middle-api.key': No such file or directory Fuentes#
- 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
Comenta este artículo#
¿Te ha servido? Compártelo y dime qué piensas.
Este artículo en Markdown · RSS · JSON feed
Nuevos artículos por correo
Un correo a la semana con nuevos artículos y labs. Puedes darte de baja cuando quieras.
Tu dirección se guarda en Kit, el servicio que envía los correos. Detalles