From 843fb582a23e7a7ebb073b9e0c2686db6d39c1f8 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Mon, 9 Jun 2025 16:58:26 +0800 Subject: [PATCH 1/4] feat: enhance auth server discovery with OAuth2 and OpenID metadata support --- .../draft/basic/authorization.mdx | 26 ++++++++++++------- docs/specification/draft/changelog.mdx | 2 ++ 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index d4aec5798..dc09fb090 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -63,9 +63,12 @@ specifies how an MCP server indicates the location of its corresponding authoriz 1. MCP servers **MUST** implement OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)). MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for authorization server discovery. -1. MCP authorization servers **MUST** provide OAuth 2.0 Authorization - Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). - MCP clients **MUST** use the OAuth 2.0 Authorization Server Metadata. +1. MCP authorization servers **MUST** provide at least one of the following discovery mechanisms: + + - OAuth 2.0 Authorization Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) + - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) + + MCP clients **MUST** support both discovery mechanisms to obtain the information required to interact with the authorization server. ### Authorization Server Discovery @@ -91,11 +94,6 @@ as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatr MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server. -#### Server Metadata Discovery - -MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414) -specification to obtain the information required to interact with the authorization server. - #### Sequence Diagram The following diagram outlines an example flow: @@ -114,7 +112,11 @@ sequenceDiagram M-->>C: Resource metadata with authorization server URL Note over C: Validate RS metadata,
build AS metadata URL - C->>A: GET /.well-known/oauth-authorization-server + alt OAuth 2.0 Authorization Server Metadata + C->>A: GET /.well-known/oauth-authorization-server + else OpenID Connect Discovery + C->>A: GET /.well-known/openid-configuration + end A-->>C: Authorization server metadata Note over C,A: OAuth 2.1 authorization flow happens here @@ -170,7 +172,11 @@ sequenceDiagram Note over C: Parse metadata and extract authorization server(s)
Client determines AS to use - C->>A: GET /.well-known/oauth-authorization-server + alt OAuth 2.0 Authorization Server Metadata + C->>A: GET /.well-known/oauth-authorization-server + else OpenID Connect Discovery + C->>A: GET /.well-known/openid-configuration + end A->>C: Authorization server metadata response alt Dynamic client registration diff --git a/docs/specification/draft/changelog.mdx b/docs/specification/draft/changelog.mdx index 7fbe7aa97..8571fe6e2 100644 --- a/docs/specification/draft/changelog.mdx +++ b/docs/specification/draft/changelog.mdx @@ -9,6 +9,8 @@ the previous revision, [2025-06-18](/specification/2025-06-18). ## Major changes +1. Enhance authorization server discovery with support for [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html). (PR [#797](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/797)) + ## Other schema changes ## Full changelog From 7487b55140639c3a78b4c459c79a81a023fe8b16 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Thu, 3 Jul 2025 16:31:41 +0800 Subject: [PATCH 2/4] feat: clarify server metadata discovery mechanisim --- .../draft/basic/authorization.mdx | 33 ++++++++++++------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index dc09fb090..aa611cc6e 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -94,6 +94,23 @@ as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatr MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server. +#### Server Metadata Discovery + +To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata. + +The discovery approach is based on [RFC8414 Section 3.1 "Authorization Server Metadata Request"](https://datatracker.ietf.org/doc/html/rfc8414#section-3.1) for OAuth 2.0 Authorization Server Metadata discovery and [RFC8414 Section 5 "Compatibility Notes"](https://datatracker.ietf.org/doc/html/rfc8414#section-5) for OpenID Connect Discovery interoperability. + +For issuer URLs with path components (e.g., `https://auth.example.com/tenant1`), clients **MUST** try endpoints in the following priority order: + +1. OAuth 2.0 Authorization Server Metadata with path insertion: `https://auth.example.com/.well-known/oauth-authorization-server/tenant1` +2. OpenID Connect Discovery with path insertion: `https://auth.example.com/.well-known/openid-configuration/tenant1` +3. OpenID Connect Discovery 1.0 legacy path appending: `https://auth.example.com/tenant1/.well-known/openid-configuration` + +For issuer URLs without path components (e.g., `https://auth.example.com`), clients **MUST** try: + +1. OAuth 2.0 Authorization Server Metadata: `https://auth.example.com/.well-known/oauth-authorization-server` +2. OpenID Connect Discovery: `https://auth.example.com/.well-known/openid-configuration` + #### Sequence Diagram The following diagram outlines an example flow: @@ -112,11 +129,8 @@ sequenceDiagram M-->>C: Resource metadata with authorization server URL Note over C: Validate RS metadata,
build AS metadata URL - alt OAuth 2.0 Authorization Server Metadata - C->>A: GET /.well-known/oauth-authorization-server - else OpenID Connect Discovery - C->>A: GET /.well-known/openid-configuration - end + C->>A: GET Authorization server metadata endpoint + Note over C,A: Try OAuth 2.0 and OpenID Connect
discovery endpoints in priority order A-->>C: Authorization server metadata Note over C,A: OAuth 2.1 authorization flow happens here @@ -172,12 +186,9 @@ sequenceDiagram Note over C: Parse metadata and extract authorization server(s)
Client determines AS to use - alt OAuth 2.0 Authorization Server Metadata - C->>A: GET /.well-known/oauth-authorization-server - else OpenID Connect Discovery - C->>A: GET /.well-known/openid-configuration - end - A->>C: Authorization server metadata response + C->>A: GET Authorization server metadata endpoint + Note over C,A: Try OAuth 2.0 and OpenID Connect
discovery endpoints in priority order + A-->>C: Authorization server metadata alt Dynamic client registration C->>A: POST /register From 4daa8b20386c5480ef06d23911f0a649cdd13ba5 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Tue, 15 Jul 2025 05:33:52 +0800 Subject: [PATCH 3/4] refactor: remove legacy designation from OpenID Connect Discovery path appending --- docs/specification/draft/basic/authorization.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index aa611cc6e..25aefc483 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -104,7 +104,7 @@ For issuer URLs with path components (e.g., `https://auth.example.com/tenant1`), 1. OAuth 2.0 Authorization Server Metadata with path insertion: `https://auth.example.com/.well-known/oauth-authorization-server/tenant1` 2. OpenID Connect Discovery with path insertion: `https://auth.example.com/.well-known/openid-configuration/tenant1` -3. OpenID Connect Discovery 1.0 legacy path appending: `https://auth.example.com/tenant1/.well-known/openid-configuration` +3. OpenID Connect Discovery 1.0 path appending: `https://auth.example.com/tenant1/.well-known/openid-configuration` For issuer URLs without path components (e.g., `https://auth.example.com`), clients **MUST** try: From 245429b84dd9ea8976b06e4dfa77cd5acefc9f40 Mon Sep 17 00:00:00 2001 From: Xiao Yijun Date: Thu, 17 Jul 2025 16:08:17 +0800 Subject: [PATCH 4/4] feat: require PKCE support verification in authorization server metadata --- .../draft/basic/authorization.mdx | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/specification/draft/basic/authorization.mdx b/docs/specification/draft/basic/authorization.mdx index 25aefc483..ed417ff90 100644 --- a/docs/specification/draft/basic/authorization.mdx +++ b/docs/specification/draft/basic/authorization.mdx @@ -98,18 +98,18 @@ MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond app To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata. -The discovery approach is based on [RFC8414 Section 3.1 "Authorization Server Metadata Request"](https://datatracker.ietf.org/doc/html/rfc8414#section-3.1) for OAuth 2.0 Authorization Server Metadata discovery and [RFC8414 Section 5 "Compatibility Notes"](https://datatracker.ietf.org/doc/html/rfc8414#section-5) for OpenID Connect Discovery interoperability. +The discovery approach is based on [RFC8414 Section 3.1 "Authorization Server Metadata Request"](https://datatracker.ietf.org/doc/html/rfc8414#section-3.1) for OAuth 2.0 Authorization Server Metadata discovery and [RFC8414 Section 5 "Compatibility Notes"](https://datatracker.ietf.org/doc/html/rfc8414#section-5) for OpenID Connect Discovery 1.0 interoperability. For issuer URLs with path components (e.g., `https://auth.example.com/tenant1`), clients **MUST** try endpoints in the following priority order: 1. OAuth 2.0 Authorization Server Metadata with path insertion: `https://auth.example.com/.well-known/oauth-authorization-server/tenant1` -2. OpenID Connect Discovery with path insertion: `https://auth.example.com/.well-known/openid-configuration/tenant1` +2. OpenID Connect Discovery 1.0 with path insertion: `https://auth.example.com/.well-known/openid-configuration/tenant1` 3. OpenID Connect Discovery 1.0 path appending: `https://auth.example.com/tenant1/.well-known/openid-configuration` For issuer URLs without path components (e.g., `https://auth.example.com`), clients **MUST** try: 1. OAuth 2.0 Authorization Server Metadata: `https://auth.example.com/.well-known/oauth-authorization-server` -2. OpenID Connect Discovery: `https://auth.example.com/.well-known/openid-configuration` +2. OpenID Connect Discovery 1.0: `https://auth.example.com/.well-known/openid-configuration` #### Sequence Diagram @@ -343,9 +343,19 @@ Specifically: An attacker who has gained access to an authorization code contained in an authorization response can try to redeem the authorization code for an access token or otherwise make use of the authorization code. (Further described in [OAuth 2.1 Section 7.5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-7.5)) -To mitigate this, MCP clients **MUST** implement PKCE according to [OAuth 2.1 Section 7.5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-7.5.2). +To mitigate this, MCP clients **MUST** implement PKCE according to [OAuth 2.1 Section 7.5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-7.5.2) and **MUST** verify PKCE support before proceeding with authorization. PKCE helps prevent authorization code interception and injection attacks by requiring clients to create a secret verifier-challenge pair, ensuring that only the original requestor can exchange an authorization code for tokens. +MCP clients **MUST** use the `S256` code challenge method when technically capable, as required by [OAuth 2.1 Section 4.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-4.1.1). + +Since OAuth 2.1 and PKCE specifications do not define a mechanism for clients to discover PKCE support, MCP clients **MUST** rely on authorization server metadata to verify this capability: + +- **OAuth 2.0 Authorization Server Metadata**: If `code_challenge_methods_supported` is absent, the authorization server does not support PKCE and MCP clients **MUST** refuse to proceed. + +- **OpenID Connect Discovery 1.0**: While the [OpenID Provider Metadata](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata) does not define `code_challenge_methods_supported`, this field is commonly included by OpenID providers. MCP clients **MUST** verify the presence of `code_challenge_methods_supported` in the provider metadata response. If the field is absent, MCP clients **MUST** refuse to proceed. + +Authorization servers providing OpenID Connect Discovery 1.0 **MUST** include `code_challenge_methods_supported` in their metadata to ensure MCP compatibility. + ### Open Redirection An attacker may craft malicious redirect URIs to direct users to phishing sites.