iamops.dev
Argo en X Feed RSS
ESEspañol

Labs Técnico 6 min de lectura

Flujo on-behalf-of de Microsoft Entra para la capa intermedia de un agente: certificado, sin secretos

Lab en un tenant de prueba: device code, la API del agente cambia el token on-behalf-of con certificado, sin secretos; un scope sin consentimiento falla.

Dos capturas de mi laboratorio de Entra: la página de permisos de API de la app intermedia y una tabla en el terminal que compara audience, ID de aplicación y scope del token de usuario y de los dos tokens on-behalf-of.
En resumenPara los agentes que llaman a API en nombre de un usuario con sesión…
  • 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 6 pasos

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.

Ir a los pasos

Cómo funciona

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:

  1. Registre la Resource API y exponga un scope delegado Data.Read (administradores y usuarios).
  2. Registre la Agent Middle API, exponga access_as_user y añada los permisos delegados Data.Read y Microsoft Graph User.Read; después conceda el consentimiento de administrador.
  3. Genere con openssl una 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.
  4. Registre el Client como cliente público (redirección http://localhost, Allow public client flows activado) con permiso para access_as_user y User.Read.
Salida de terminal de openssl con el sujeto del certificado y la huella SHA-1, sustituida por un marcador.
La credencial. Un certificado autofirmado es la única credencial de la middle API. La huella está sustituida por un marcador; la clave privada nunca se muestra.
Centro de administración de Microsoft Entra, página Certificates and secrets de la Agent Middle API con la pestaña Client secrets abierta, que muestra cero secretos de cliente.
Sin secretos. La pestaña Client secrets muestra 0. Un certificado demuestra la posesión de una clave que nunca viaja; un secreto es una cadena reutilizable que acaba en configuraciones y registros.
Centro de administración de Microsoft Entra, API permissions de la Agent Middle API: User.Read de Microsoft Graph y Data.Read de la Resource API, ambos delegados y concedidos para el directorio.
Lo que puede pedir la capa intermedia. Entra comprueba estos permisos delegados en el momento del intercambio. Lo que no figura y no tiene consentimiento no puede obtenerse aguas abajo.
Centro de administración de Microsoft Entra, Enterprise applications, Permissions del service principal de la Agent Middle API, con el consentimiento de administrador para User.Read y Data.Read.
Lo que obtuvo de verdad. Los registros de aplicación muestran lo que una app pide; los permisos del service principal muestran lo que se le dio. Las herramientas de gobierno deberían leer estos últimos.

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.

Salida de terminal de la solicitud de autorización de dispositivo y su respuesta, con tenant, ID de cliente y código de usuario sustituidos por marcadores.
Autorización de dispositivo. Los identificadores y el código de usuario son marcadores.

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.

Claims decodificados del token de usuario: la audiencia es la middle API, appid es el Client y el scope es access_as_user. Identificadores y nombre del usuario sustituidos por marcadores.
El único token del Client. Audiencia: la middle API. Aplicación: el Client. Scope: access_as_user.

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:

text
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
Claims decodificados del token OBO para la Resource API: la audiencia es la Resource API, appid la middle API, scope Data.Read, mismo ID de objeto del usuario. Identificadores sustituidos por marcadores.
Token para la Resource API. Audiencia: la Resource API. Aplicación: la middle API. Scope: Data.Read. Mismo usuario.

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.

Claims decodificados del token OBO para Microsoft Graph y respuesta de la llamada Graph me, con el nombre y el nombre principal del usuario sustituidos por marcadores.
Token para Microsoft Graph y después una llamada a /me. Un solo inicio de sesión se ramifica en varios tokens, cada uno ligado a una audiencia. El nombre y el nombre principal del usuario son marcadores.

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.

Tabla en paralelo de audiencia, appid, scope, ID de objeto e ID de tenant para el token de usuario y los dos tokens OBO. Identificadores sustituidos por marcadores.
Tres tokens en paralelo. Mismo usuario y mismo tenant; en cada salto cambian la audiencia y la aplicación que llama.

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

Salida de terminal de un error invalid_grant AADSTS65001: el usuario o el administrador no ha dado su consentimiento para usar la aplicación. ID de aplicación, ID de traza e ID de correlación sustituidos por marcadores.
AADSTS65001. El consentimiento se comprueba al emitir el token, sobre el service principal de la capa intermedia. Para un agente no interactivo no hay recurso a una solicitud interactiva.

Trampas habituales#

  • Se pierde el cliente original. Los tokens OBO v1 solo registran la última aplicación (appid). No hay claim act como 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#

  1. 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.
  2. Mantenga mínimos los scopes delegados de la capa intermedia y revíselos en el service principal.
  3. Deje el Client sin credenciales. Solo podrá guardar el token del usuario para la middle API, nunca un token posterior.
  4. Planifique el cruce de datos de auditoría (usuario, agente, audiencia posterior), porque los tokens OBO no conservan el primer salto.
  5. 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

bash · env.sh
# 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"
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
text · portal-checklist.txt
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

salida
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
bash · make-cert.sh
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
text · upload-steps.txt
# 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

salida
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
bash · devicecode.sh
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
bash · poll.sh
#!/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
bash · run-poll.sh
chmod +x poll.sh && ./poll.sh   # now open the verification URI, enter the code and approve

Salida esperada

salida
{
  "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
python · obo.py
"""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))
bash · run-obo.sh
python3 obo.py > obo_result.json
jq '.step2_obo_for_resource_api, .step3_obo_for_graph, .step4_graph_me' obo_result.json

Salida esperada

salida
{
  "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
bash · compare.sh
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

salida
{
  "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
bash · cleanup.sh
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

salida
ls: cannot access 'middle-api.key': No such file or directory

Fuentes#

Comenta este artículo#

¿Te ha servido? Compártelo y dime qué piensas.

Seguir en X

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

Artículos y labs relacionados