fix: update MCP Inspector authorization flow to reflect PRM resource id (+instructions)

[Justrebl]

PR: Fix MCP Inspector authorization flow to reflect PRM resource id

Concrete repro step before fix :

Purpose

• Aligns the mcp-prm-oauth lab with RFC 9728 (Protected Resource Metadata) by using the full APIM MCP endpoint URL ({APIMGatewayURL}/{mcpApiPath}/mcp) as the OAuth resource identifier, instead of the Entra application client_id.
• Fixes the MCP Inspector / VS Code authorization flow so the advertised resource, scopes_supported, JWT audience, WWW-Authenticate metadata URL, and the Entra app Application ID URI all reference the same PRM resource id and are consistent end-to-end.
• Updates the Entra ID app registration so it exposes the correct identifierUris (Application ID URI) and is configured as a public client (Authorization Code + PKCE) with a federated credential trusting the user-assigned managed identity.
• Introduces a new modules/apim/v4/apim.bicep module targeting the 2025-09-01-preview API Management API version and migrates the lab to it.
• Improves lab clean-up to also remove the Entra ID app registration (which lives in Entra ID, not in the resource group) and makes resource/app naming deterministic.

Does this introduce a breaking change?

[ ] Yes
[x] No

Pull Request Type

What kind of change does this Pull Request introduce?

[x] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Documentation content changes
[ ] Other... Please describe:

How to Test

• Get the code

git clone https://github.com/Azure-Samples/AI-Gateway.git
cd AI-Gateway
git checkout fix/mcp-prm-inspector-authentication

• Test the code

1. Open labs/mcp-prm-oauth/mcp-prm-oauth.ipynb and run all cells to deploy the
   infrastructure (APIM v4 module, Container App MCP server, Entra app registration).

2. Run the "Test the authorization WITHOUT a valid token" cell and confirm a
   401 Unauthorized is returned, with a WWW-Authenticate header pointing at
   {APIMGatewayURL}/.well-known/oauth-protected-resource/{mcpApiPath}/mcp/.

3. Test with the MCP Inspector:
   - Run `npx @modelcontextprotocol/inspector`.
   - Transport: Streamable HTTP; URL: the mcp_api_endpoint value.
   - In Auth Settings, set the Scope to
     <mcp_api_endpoint>/user_impersonate (the value advertised in
     scopes_supported of the Protected Resource Metadata).
   - Run Quick OAuth Flow, consent, and confirm the tool call succeeds.

4. (Optional) Repeat the flow with VS Code GitHub Copilot (MCP: Add Server).

5. Run clean-up-resources.ipynb and confirm both the Azure resources and the
   Entra app registration are removed.

What to Check

Verify that the following are valid:

• The Protected Resource Metadata (mcp-prm.policy.xml) advertises resource = {APIMGatewayURL}/{mcpApiPath}/mcp and scopes_supported = {APIMGatewayURL}/{mcpApiPath}/mcp/user_impersonate.
• The validate-azure-ad-token policy (mcp-api.policy.xml) accepts both the MCP client_id and the {APIMGatewayURL}/{mcpApiPath} audience.
• The 401 WWW-Authenticate header returns resource_metadata pointing to .well-known/oauth-protected-resource/{mcpApiPath}/mcp/.
• The Entra app registration (mcp-entra-app.bicep) is created with the correct identifierUris (Application ID URI), public-client configuration, and federated credential.
• The lab deploys against the new modules/apim/v4/apim.bicep module and the 2025-09-01-preview resource API versions.
• MCP Inspector and VS Code complete the OAuth flow and successfully invoke the tool.
• Clean-up removes the app registration in addition to the resource group resources.