Workarounds Required to Support Microsoft Azure as Auth Server

[2underscores]

Support Azure for Enterprise Adoption

• With MCP SDK, Azure AD cannot be used as the Authorisation Server (AS) as Azure:
  • Does not advertise PKCE in AS metadata
  • Uses scope param instead of RFC 8707's resource param
• MCP SDK should support Azure as an AS, as Azure is extremely commonly used, particularly in enterprise.

PKCE Not Advertised

• MCP spec mandates implementation of RFC 8414 - OAuth 2.0 Authorization Server Metadata, and Azure supports the metadata endpoint
• The code_challenge_methods_supported field lists the PKCE methods supported by the AS. According to RFC8414 "If omitted, the authorization server does not support PKCE."
• Azure AS omits code_challenge_methods_supported, but does support PKCE with method S256
• This one is on Azure and It's a known issue for years. To support Azure, a bypass is needed that ignores the field omission and assumes PKCE is supported, specifically for Azure.
• Bug already raised - Azure OIDC discovery metadata missing code_challenge_methods_supported breaks S256 PKCE validation #832
  • According to RFC 8414, this is actually an Azure bug

scope instead of resource

• RFC 8707 - Resource Indicators for OAuth 2.0 is an optional extension to OAuth, that MCP has as mandatory.
• It introduces the resource param that indicates which protected resource the client is requesting access to.
  • This is included in /authorize and /token endpoints, and in the JWT's aud claim.
• Azure v2 endpoints do not implement RFC 8707. They implement a very similar scope parameter in place of the resource param
  • scope is a superset, and includes both the "resource" access is being requested to, and the actions ("scopes") to perform on it.
• Azure AS will fail if resource is provided (i.e. It does not ignore/silently drop it)
• To support Azure, conditional logic is needed to provide scope in place of resource with the required minor change to value.

Other Related Azure Issues

• Azure AS metadata endpoint is at /.well-known/openid-configuration rather than /.well-known/oauth-authorization-server introduced in RFC 8414
  • This is somewhat common and mentioned in the RFC
  • This SDK added proper support for this with feat: support oidc discovery in client sdk #652
• Azure doesn't support RFC 7591 - OAuth 2.0 Dynamic Client Registration (DCR), however this is only recommended (i.e. not mandated) by spec and this SDK supports static client ID.

This commit has one implementation of the compatibility changes needed to support Azure as AS.

[pcarleton]

One solution in the SDK's is to make auth more pluggable, so it's easy to override the behaviors needed to handle these quirks without the SDK having to consider every single one. there's this PR in progress to work on that: #485

that means if a developer has a client they want to work with an AS that is doing something unusual, they can easily swap out the auth impl to make it easier.

the downside of that approach, which becomes clear with inspector, is that if you have a client that's expected to be generic and connect to everything, you need the "every oddball AS special case" implementation.

I'd prefer we not litter the SDK with a bunch of vendor specific carve-outs, and also don't want to litter Inspector with it. one compromise would be to have an "advanced" flow in inspector where you can more easily directly manipulate all the params/headers.

on the particular issue regarding resource vs. scope, there's a conversation about scope here: modelcontextprotocol/modelcontextprotocol#835 i think we should probably just solve this one that way.

going to close this one for now

[2underscores]

I'd prefer we not litter the SDK with a bunch of vendor specific carve-outs

Yeah very understandable, it's pretty icky code. We'll continue maintaining our fork with this for now, but hoping for something in the future to standardise this.

the downside of that approach, which becomes clear with inspector, is that if you have a client that's expected to be generic and connect to everything, you need the "every oddball AS special case" implementation.

Generic client fits our use case sadly, and IMO is what a lot of MCP clients will do (like the LSP analogy for editors and languages, MCP enables that interoperability and clients will connect to a variety of MCP servers).

For future reference on our use case (i think it's representative of a lot of enterprise MCP usage) - some of our MCPs use Azure as both the AS and IdP for authentication, and some use a vendor's AS, with IdP federation to our Azure (where the vendors AS is spec compliant, this SDK works for us).

IMO Azure (and maybe 0-3 others) are large enough, that where spec break is minor, carve outs for them specifically may improve standardisation by making a single SDK (this one) more broadly adopted rather than forcing forks if the big AS don't change. For reasons here, I don't think Azure is going to change anytime soon on these ones.

Thanks very much for reviewing and redirecting to the WIP links!