Repository navigation
Description
Sub-issue F: Entra v1 api://<app-id>/<scope> scope verbatim pass-through in PRM + audience normalization
Parent: #988
Labels: enhancement, oauth, entra-id, mcp-spec, authentication, subtask
Phase: 2
Depends on: A
Blocks: none (but coordinates with E)
Summary
When the configured IdP is Microsoft Entra v1, the PRM scopes_supported array MUST contain scope strings in the exact api://<app-id>/<scope-name> form that Entra expects on the /authorize request. Anything else and Entra returns AADSTS650053: The application ... asked for scope X that doesn't exist on the resource Y. This issue tracks the verbatim pass-through logic in the PRM endpoint plus the dual-audience acceptance on token validation.
Background
Entra v1 (the api://... scope form) requires the client to request scopes as api://<app-id>/<scope> (or api://<app-uri>/<scope>), not just the bare scope name. Unlike Entra v2 which accepts fragment-only scopes, v1 rejects the request if the resource prefix is missing.
Matching behavior on the token side: the aud claim for an Entra v1-issued token can be either the bare GUID (<app-id>) or the URI form (api://<app-id>). The Registry's audience validator must accept both as equivalent.
This is a known failure mode both for our own Registry deployment (observed in field deployments using Entra v1) and for the AgentCore Identity integration. Fixing it here unblocks both.
Existing code at auth_server/providers/entra.py:149 already does dual-audience acceptance on the inbound path — this issue ensures the PRM emitted by sub-issue A mirrors that behavior on the outbound advertisement path so Claude Code / Cursor / VS Code send the right scope strings in the first place.
Scope
In scope
- PRM
scopes_supportedemission for Entra v1:- Read the registered MCP server scopes from the gateway's registration source.
- If provider is Entra and the configured scope format is v1, emit each scope as
api://<app-id-or-uri>/<scope-name>verbatim. No URL encoding, no transformation. - The
<app-id-or-uri>prefix must match the value that Entra expects on/authorize; read from provider config, not reconstructed.
- PRM
scopes_supportedemission for Entra v2:- Emit bare scope names (Entra v2 accepts fragment form).
- PRM
scopes_supportedemission for non-Entra providers:- Emit whatever the provider declares. Keycloak, Okta, Cognito, Auth0 have their own canonical scope forms; do not transform.
- Audience normalization on token validation (coordinates with sub-issue E):
- Accept both
api://<app-id>and bare<app-id>GUID as equivalent audience values for Entra v1 tokens. - Formalize the logic currently at auth_server/providers/entra.py:149 as a provider-level method, not ad-hoc code.
- Accept both
- Regression tests:
- Entra v1 provider config → PRM emits
api://<app-id>/mcp.readform. - Entra v2 provider config → PRM emits
mcp.readform. - Keycloak / Okta / Cognito / Auth0 → PRM emits whatever the provider declares.
- Audience validator accepts both Entra v1 forms.
- Regression test for the AADSTS650053 failure mode: mock an Entra v1
/authorizeinteraction and assert the scope strings match.
- Entra v1 provider config → PRM emits
Out of scope
- General multi-IdP configuration (→ MCPGW OAuth/OIDC and M2M token integration: security gaps and multi-IdP support #895, Add MCPGW OIDC env vars to ECS task definition, tfvars, and Helm charts #896).
- CIMD publisher / consumer (→ B, C).
- Fixing IdP-side config; operators own their Entra app registration.
Design notes
- Put the scope-format logic in the provider module (auth_server/providers/entra.py). The discovery endpoint from sub-issue A calls
provider.protected_resource_metadata(); that provider method owns the formatting. - Config surface: add an explicit
entra_scope_format: v1 | v2setting (defaultv2), with clear docs on when to use which. Don't auto-detect; operators need a predictable behavior. - Dual-audience acceptance is asymmetric: we accept either form inbound, we emit one form outbound (the one Entra expects). Don't conflate.
Acceptance criteria
- PRM endpoint emits scope strings in the format the configured Entra version expects, verbatim, no encoding.
- Non-Entra providers unchanged.
- Audience validator on
/oauth/tokenand MCP-data-plane paths accepts bothapi://<app-id>and bare<app-id>forms for Entra v1. - Config surface documented:
entra_scope_format: v1 | v2. - Regression tests for each provider.
- Regression test covering the AADSTS650053 failure mode.
- Docs page in docs/ addressing: "if you're on Entra v1, set this flag; if you're on Entra v2, don't."
- Stakeholder update: notify owners of the AgentCore Identity integration and any field deployments using Entra v1 that this is scoped and tracked.
Risks and open questions
- Version detection. Can we auto-detect Entra v1 vs v2 from the issuer URL? Yes (Entra v1 issuer contains
/v1.0/; v2 contains/v2.0/), but auto-detection hides operator intent. Stick with explicit config. - App-uri vs app-id form. Entra allows either
api://<app-id>or a customapi://<tenant-specific-uri>. Provider config must capture whichever the operator set up in the Entra app registration.
References
- Microsoft Entra v1 vs v2 endpoints
- AADSTS650053 error reference
- auth_server/providers/entra.py:149 (dual-audience pattern)
- Recommendation doc §6 Phase 2: .scratchpad/coding-assistant-oauth/recommendation-2026-05-04.md
- Related (but distinct) threads: Entra v1 scope format interop, Entra PKCE interop, AgentCore Identity verbatim scope requirement
Activity
feat(oauth): add provider AS-metadata API and gateway PRM helpers (ag…
feat(oauth): implement RFC 8414 metadata for Cognito, Auth0, Okta, En…
docs(oauth): add operator guide for PRM + AS-metadata discovery (agen…
zoltan-fedor commentedon Jul 28, 2026
We are really looking forward for this to be added to
1.28.0- being one of the last missing pieces of the complete Entra OBO flow.feat(entra): v1 api:// scope verbatim pass-through in PRM + audience …
refactor(oauth): single source of truth for the Entra per-server-PRM …