En bref
- Pour les agents qui appellent des API au nom d'un utilisateur connecté, la réponse actuelle d'Entra est le flux on-behalf-of (OBO) ; ID-JAG n'y est aujourd'hui qu'une enquête de disponibilité.
- La middle API se prouve avec une assertion signée par certificat et ne détient aucun secret client.
- Une connexion produit des jetons distincts par audience : l'utilisateur reste le même et l'application appelante change.
- Un scope sans consentement échoue avec AADSTS65001 ; c'est le consentement sur le service principal qui compte.
- Les jetons OBO ne conservent pas le client d'origine, les audits doivent donc croiser les journaux de connexion.
Refaire ce lab
J’ai écrit ce lab pour que vous puissiez le refaire vous-même. Chaque étape contient les commandes à copier et la sortie que j’ai obtenue, et vous pouvez la cocher une fois faite. Les coches restent uniquement dans ce navigateur.
Copie un prompt prêt à l’emploi pour Claude Code, Cursor, Codex ou tout autre agent de code. Pour les environnements de test uniquement.
Afficher le prompt
I want to run a hands-on lab from iamops.dev, and I would like your help to do it safely. Lab: Flux on-behalf-of de Microsoft Entra pour la couche intermédiaire d'un agent : certificat, aucun secret client Read the whole lab here (Markdown): https://iamops.dev/fr/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.
Le 14 novembre 2026, Microsoft a ajouté un article Learn qui nomme pour la première fois ID-JAG à côté de Microsoft Entra Agent ID et ouvre un formulaire de manifestation d’intérêt. C’est une enquête de disponibilité, pas une fonction livrée : Entra n’émet ni n’accepte aujourd’hui d’ID-JAG. Pour les agents qui doivent appeler des API pour un utilisateur connecté, la réponse actuelle d’Entra est le flux on-behalf-of (OBO). Je l’ai exécuté de bout en bout dans un tenant jetable et j’ai noté ce que fait chaque étape.
Ce que montre le laboratoire#
Trois inscriptions d’applications représentent un système d’agents :
| Application | Rôle | Identifiant |
|---|---|---|
| Client | L’interface ou la ligne de commande de l’agent. Client public, connexion par device code. | Aucun |
| Agent Middle API | Le back-end de l’agent. Il effectue l’échange OBO. | Un certificat X.509, zéro secret client |
| Resource API | L’API en aval. Expose le scope délégué Data.Read. |
s. o. |
L’utilisateur se connecte une fois au Client. Le Client détient un jeton dont l’audience est la seule middle API. La middle API l’échange contre un jeton pour la Resource API et un autre pour Microsoft Graph, en prouvant son identité par une assertion signée avec un certificat plutôt que par un secret.
Mise en place#
Utilisez un tenant de test séparé (Entra ID Free suffit, aucune ressource Azure n’est nécessaire). Les jetons OBO portent de vrais claims d’utilisateur, et un tenant jetable tient les expériences à l’écart du consentement, de l’accès conditionnel et des journaux d’audit de production. Dans le portail :
- Inscrivez la Resource API et exposez un scope délégué
Data.Read(administrateurs et utilisateurs). - Inscrivez l’Agent Middle API, exposez
access_as_useret ajoutez les autorisations déléguéesData.Readet Microsoft GraphUser.Read, puis accordez le consentement administrateur. - Générez avec
opensslune clé RSA de 2048 bits et un certificat autosigné de 60 jours, gardez la clé privée sur la machine (mode 0600) et ne téléversez que le certificat public sous Certificates & secrets. - Inscrivez le Client comme client public (redirection
http://localhost, Allow public client flows activé) avec l’autorisation pouraccess_as_useretUser.Read.




Le déroulement#
Connexion par device code. Le Client demande un code au point de terminaison devicecode v2.0. La requête ne porte que l’ID du Client et le scope de la middle API, aucun secret. L’utilisateur saisit le code sur un second appareil et Entra affiche un contrôle « approuver la connexion sur un autre appareil » qui nomme l’application et le lieu ; l’utilisateur doit l’approuver à la main.

Le jeton utilisateur. Après l’approbation, le Client interroge le point de terminaison des jetons. Son jeton est inutilisable directement contre la Resource API ou Graph, car son audience est la middle API.

L’échange. La middle API construit une assertion client (un JWT RS256 avec l’empreinte du certificat dans x5t ; émetteur et sujet sont son propre ID de client ; audience : le point de terminaison des jetons ; dix minutes de validité), la signe avec la clé privée et envoie la requête 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 même assertion avec le scope https://graph.microsoft.com/User.Read renvoie un jeton Graph, que le laboratoire utilise une fois pour GET /v1.0/me.

Comparer les trois jetons. L’utilisateur ne change jamais. L’audience suit l’API appelée et appid passe du Client à la middle API.

Le test négatif. Demander https://graph.microsoft.com/Mail.Read, auquel personne n’a consenti, échoue au service de jetons :

Pièges#
- Le client d’origine est perdu. Les jetons OBO v1 ne conservent que la dernière application (
appid). Il n’y a pas de claimactcomme dans une implémentation de la RFC 8693 ; un audit doit donc joindre les journaux de connexion pour reconstituer la chaîne. - L’audience entrante doit être la middle API. Un jeton destiné à une autre application est rejeté : c’est la protection contre le confused deputy.
- Le device code exige « Allow public client flows ». C’est aussi le flux qu’exploite le device code phishing. L’écran « approuver la connexion sur un autre appareil » est la parade de Microsoft ; apprenez aux utilisateurs à appuyer sur « Ce n’était pas moi » et restreignez le flux par accès conditionnel là où les agents n’en ont pas besoin.
- Seul compte le consentement administrateur sur le service principal, pas ce que liste l’inscription.
Enseignements de sécurité#
- Utilisez un certificat ou un identifiant fédéré pour la couche intermédiaire. Pas de secret, c’est rien de réutilisable à laisser fuiter depuis la configuration, les variables de CI ou les journaux.
- Gardez minimaux les scopes délégués de la couche intermédiaire et vérifiez-les sur le service principal.
- Laissez le Client sans identifiant. Il ne pourra jamais détenir que le jeton de l’utilisateur pour la middle API, jamais un jeton en aval.
- Prévoyez la jointure d’audit (utilisateur, agent, audience en aval), car les jetons OBO ne gardent pas le premier maillon.
- Consignez quelle autorisation chaque étape utilise (OBO aujourd’hui ; ID-JAG quand Entra le prendra en charge) et où se trouve le consentement, pour que les revues d’accès voient les autorisations des service principals.
Ce qui n’a pas été exécuté#
Les blueprints et identités d’agent d’Entra Agent ID (le même laboratoire avec autorisations héritables) n’ont pas été exécutés. La stratégie d’accès conditionnel qui bloque le device code n’a pas été testée. Les exercices complémentaires (retirer le consentement et répéter l’échange, claims facultatifs, jetons v2) n’ont pas été exécutés. Les captures du portail sont recadrées sur le contenu de la page : la barre du navigateur, le menu de profil et tous les identifiants de tenant, d’applications et d’utilisateurs sont supprimés. Aucun enregistrement n’est publié pour ce laboratoire.
Les images du terminal ont été générées à partir de la sortie enregistrée de l’exécution, avec les identifiants remplacés par des espaces réservés. Les captures du portail ne montrent que le contenu de la page.
Refaire ce lab#
Ce lab demande un tenant Entra jetable, openssl, curl, jq et Python 3, sans autre dépendance. Comptez environ 60 minutes, surtout pour cliquer une fois dans le portail. Ouvrez chaque étape, copiez les blocs et comparez la sortie avec la mienne.
Chaque valeur entre chevrons est un espace réservé pour votre environnement de test. Rien sur cette page n’est un identifiant ou un secret réel.
Définissez vos variables une seule fois
# 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" Étapes terminées : 0 sur 6
Étape 1Enregistrer les trois applications dans un tenant de test
Objectif. Créez la Resource API, l'Agent Middle API et le Client. Seule l'API intermédiaire reçoit un identifiant, et c'est un certificat.
Prérequis
- Un tenant de test séparé (Entra ID Free suffit) dont vous êtes Global Administrator
- Ne le faites jamais dans un tenant de production : les jetons OBO portent de vraies claims utilisateur
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. Résultat attendu
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>" Étape 2Créer le certificat de l'API intermédiaire
Objectif. Créez une clé de 2048 bits et un certificat autosigné de 60 jours. La clé privée reste sur cette machine ; seul le certificat public va chez Entra.
Prérequis
- openssl 1.1 ou plus récent
- env.sh chargé dans ce 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. Résultat attendu
subject=CN = agent-middle-api
notBefore=<start-date>
notAfter=<end-date>
sha1 Fingerprint=<certificate-thumbprint> Étape 3Connecter l'utilisateur avec le device code
Objectif. Le Client demande un device code avec seulement son ID et le scope de l'API intermédiaire. Vous approuvez la connexion dans un navigateur sur un autre appareil et le script attend.
Prérequis
- Allow public client flows est activé sur le Client
- Un utilisateur de test du tenant qui peut se connecter
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 Résultat attendu
{
"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 Étape 4Échanger le jeton au nom de l'utilisateur
Objectif. L'API intermédiaire signe une client assertion avec le certificat et échange le jeton de l'utilisateur contre un jeton pour la Resource API et un pour Microsoft Graph.
Prérequis
- user_token.json de l'étape précédente et le certificat envoyé à l'API intermédiaire
- Python 3.9 ou plus récent ; aucun paquet à installer
"""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 Résultat attendu
{
"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>"
} Étape 5Comparer les jetons et demander un scope sans consentement
Objectif. Lisez les trois jetons côte à côte, puis regardez l'erreur AADSTS65001 pour Mail.Read.
Prérequis
- obo_result.json de l'étape précédente
- column (de util-linux ou bsdmainutils) pour le tableau
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' Résultat attendu
{
"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> Étape 6Nettoyage
Objectif. Supprimez la clé, le certificat, les fichiers de jetons et les enregistrements d'applications.
Prérequis
- Vous êtes dans le répertoire où vous avez lancé le 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. Résultat attendu
ls: cannot access 'middle-api.key': No such file or directory Sources#
- 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
Discuter de cet article#
Utile ? Partagez-le et dites-moi ce que vous en pensez.
Cet article en Markdown · RSS · JSON feed
Les nouveaux articles par e-mail
Un e-mail par semaine avec les nouveaux articles et labs. Désinscription à tout moment.
Votre adresse est conservée chez Kit, le service qui envoie les e-mails. Détails