feat: Add runtime token exchange, OBO, cross-tenant, and permission granting

[ArLucaID]

Addresses 6 gaps in the entra-agent-id skill:

1. Runtime token exchange — Added fmi_path two-step exchange pattern (parent token via client_credentials + fmi_path, then client_assertion exchange for Graph-scoped Agent Identity token). Covers both autonomous (app-only) and OBO (delegated) modes with complete code samples.

2. fmi_path parameter — Documented the fmi_path parameter on the standard /oauth2/v2.0/token endpoint that targets a specific Agent Identity. Clarified this is NOT RFC 8693 token exchange (which returns AADSTS82001).

3. OBO/delegated flow — Added Blueprint API configuration (identifierUris, oauth2PermissionScopes, preAuthorizedApplications, optionalClaims), user token audience requirements, and complete OBO exchange code.

4. Cross-tenant guidance — Documented that fmi_path works cross-tenant when the Blueprint is multi-tenant. Critical rule: step 1 must target the Agent Identity's home tenant, not the Blueprint's (AADSTS700211 otherwise).

5. Permission granting — Added appRoleAssignments for autonomous mode and oauth2PermissionGrants for OBO mode, with per-agent scoping examples.

6. oauth2-token-flow.md completion — Option B now shows the full two-step exchange (was incomplete — stopped at Blueprint token). Added Option C for OBO flow. Added cross-tenant exchange section.

Also included

• Updated acceptance-criteria.md with sections 9-12 covering runtime exchange, OBO, cross-tenant, and permission grant patterns (correct/incorrect examples)
• Added Troubleshooting table with 8 common errors and fixes
• Tested patterns verified against live Entra endpoints (same-tenant autonomous, cross-tenant fmi_path exchange, OBO with delegated permissions)

Files changed (3 files, +810 / -14)

• .github/skills/entra-agent-id/SKILL.md
• .github/skills/entra-agent-id/references/acceptance-criteria.md
• .github/skills/entra-agent-id/references/oauth2-token-flow.md

[ArLucaID]

@thegovind / @spboyer : Could I get some help in merging this one? I don't have permissions to request reviewers.

[thegovind]

Review summary

Substantial, security-sensitive content. The two-step fmi_path exchange pattern, the AADSTS82001/AADSTS700211/AADSTS50013 failure callouts, and the cross-tenant rule (step 1 against the Agent Identity's home tenant) are all correctly framed. Code samples avoid hardcoded secrets and use parameters cleanly. One real bug to fix and a few recommendations.

Issues

🔴 Blocking

• Regression at entra-agent-id/SKILL.md L53. The diff turns

  -AZURE_TENANT_ID=<your-tenant-id>
  +AZURE_TENANT_ID=<your tenant-id>
  

  The hyphen was replaced by a space, which would surface in copy-paste as an invalid .env value. Looks like an unintended edit while reformatting; please restore <your-tenant-id>.

🟡 Recommended

• Prefer msal for token-acquisition samples (or at least cross-link). The new examples use urllib.request against /oauth2/v2.0/token directly. That's instructive for showing the wire format, but it bypasses MSAL's caching, retry/throttling, PKCE, and proof-of-possession features. Production callers should use msal.ConfidentialClientApplication (and its acquire_token_on_behalf_of for OBO). Either:
  • Add an "msal equivalent" code block alongside the raw urllib one for the autonomous and OBO exchanges, or
  • Add a one-line note: "For production use msal — these raw samples are illustrative of the wire format only".
• Token logging hygiene callout. A skill that walks through three different token shapes (parent token, app-only Graph token, OBO Graph token) is exactly the kind agents may be tempted to log for debugging. Add an explicit "do not log raw tokens, including parent tokens" line in the ## Key Rules section so the agent doesn't paste print(parent_token) into user code.
• Audience validation guidance. When the OBO flow returns a delegated Graph token, callers should validate aud and idtyp (the optional claim you correctly added to optionalClaims). Today the skill teaches acquire; please add a short "Validating the user token at the API" subsection so the Blueprint API resource side of the flow is also covered.
• scope=.../.default rule wording. The "Both exchanges MUST use /.default scope" bullet is correct; please tighten the rationale: it's because Entra resolves the consented scope set from oauth2PermissionGrants / appRoleAssignments rather than the request — which is the whole point of per-Agent-Identity scoping. One extra sentence would lock in the why so readers don't second-guess later.
• AZURE_CLIENT_SECRET in env-var block. The Environment Variables block in SKILL.md retains AZURE_CLIENT_SECRET=<app-registration-secret>. Since the Blueprint can also use WIF / federated identity (and the skill teaches this), the env-var snippet should at least mention WIF as the preferred path and client_secret as the fallback. Avoid teaching beginners that secrets-in-env is the canonical setup.

🟢 Nits

• Worth marking the public preview status of fmi_path if it's still preview at GA cut-over. Skills loaded into agent context outlive their preview windows; one explicit version/availability note prevents stale guidance.
• Long uuid-generated scope_id (str(uuid.uuid4())) for oauth2PermissionScopes[].id is correct, but readers may not realize this id must be stable across PATCHes (regenerating it breaks existing consents). Add one line.
• Acceptance-criteria sections 9–12 — make sure each "incorrect" pattern includes the exact AADSTS code it produces; that's the highest-signal recall hint for a future agent invocation.

Excellent contribution overall — this fills real gaps in the Agent Identity story.