Skip to content

[Phase 2] Entra v1 api:// scope verbatim pass-through in PRM + audience normalization #990

Closed

Description

@aarora79

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_supported emission 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_supported emission for Entra v2:
    • Emit bare scope names (Entra v2 accepts fragment form).
  • PRM scopes_supported emission 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.
  • Regression tests:
    • Entra v1 provider config → PRM emits api://<app-id>/mcp.read form.
    • Entra v2 provider config → PRM emits mcp.read form.
    • 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 /authorize interaction and assert the scope strings match.

Out of scope

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 | v2 setting (default v2), 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/token and MCP-data-plane paths accepts both api://<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 custom api://<tenant-specific-uri>. Provider config must capture whichever the operator set up in the Entra app registration.

References

Activity

  1. added
    enhancementNew feature or request
    subtaskSubtask of a larger issue
    authenticationAuthentication and security related
    mcp-specMCP specification compliance and standards
    oauthOAuth 2.0/2.1 authorization and authentication
    entra-idMicrosoft Entra ID (formerly Azure AD) integration
    on May 9, 2026
  2. modified the milestones: 1.0.25, 1.26.0 on May 9, 2026
  3. zoltan-fedor commented on Jul 28, 2026

    @zoltan-fedor

    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.

  4. self-assigned this
    on Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

authenticationAuthentication and security relatedenhancementNew feature or requestentra-idMicrosoft Entra ID (formerly Azure AD) integrationmcp-specMCP specification compliance and standardsoauthOAuth 2.0/2.1 authorization and authenticationsubtaskSubtask of a larger issue

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions