mcp: include scopes supported in the www-authenticate header (#1608)

**Description**

Add the configured scopes to the `WWW-Authenticate` headers. At
initialization time, which is when the first authentication will occur,
we don't have enough information to provide a fine-grained list of
scopes, so the best we can do is to default to the ones defined in the
protected resource metadata.

**Related Issues/PRs (if applicable)**

Fixes #1578

The addition of the header on 403 requests is implemented in
#1482, but this issue can
be closed as soon as this PR is merged, because we'll be compatible with
the latest spec.

**Special notes for reviewers (if applicable)**

cc @zhaohuabing can you take a look?

Signed-off-by: Ignasi Barrera <[email protected]>

Author: nacx

internal/controller/mcp_route_security_policy.go

@@ -323,6 +323,11 @@ func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata
 	// Add resource_metadata as per RFC 9728 Section 5.1.
 	headerValue = fmt.Sprintf(`%s, resource_metadata="%s"`, headerValue, resourceMetadataURL)
 
+	if len(metadata.ScopesSupported) > 0 {
+		// Add scope as per RFC 6750 Section 3.
+		headerValue = fmt.Sprintf(`%s, scope="%s"`, headerValue, strings.Join(metadata.ScopesSupported, " "))
+	}
+
 	return headerValue
 }
 

internal/controller/mcp_route_security_policy_test.go

@@ -654,6 +654,30 @@ func Test_buildWWWAuthenticateHeaderValue(t *testing.T) {
 			},
 			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/v1/mcp/endpoint"`,
 		},
+		{
+			name: "with empty scopes supported",
+			metadata: &aigv1a1.ProtectedResourceMetadata{
+				Resource:        "https://api.example.com/mcp",
+				ScopesSupported: []string{},
+			},
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"`,
+		},
+		{
+			name: "with single scope supported",
+			metadata: &aigv1a1.ProtectedResourceMetadata{
+				Resource:        "https://api.example.com/mcp",
+				ScopesSupported: []string{"read"},
+			},
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="read"`,
+		},
+		{
+			name: "with multiple scopes supported",
+			metadata: &aigv1a1.ProtectedResourceMetadata{
+				Resource:        "https://api.example.com/mcp",
+				ScopesSupported: []string{"read", "write"},
+			},
+			expected: `Bearer error="invalid_request", error_description="No access token was provided in this request", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="read write"`,
+		},
 	}
 
 	for _, tt := range tests {

tests/e2e/mcp_route_oauth_test.go

@@ -150,7 +150,12 @@ func TestMCPRouteOAuth(t *testing.T) {
 		require.Contains(t, wwwAuthHeader, "Bearer", "WWW-Authenticate header should contain Bearer scheme")
 
 		// Validate WWW-Authenticate header contains resource_metadata parameter.
-		require.Contains(t, wwwAuthHeader, "resource_metadata", "WWW-Authenticate header should contain resource_metadata parameter")
+		require.Contains(t, wwwAuthHeader, `resource_metadata="https://foo.bar.com/.well-known/oauth-protected-resource/mcp"`,
+			"WWW-Authenticate header should contain resource_metadata parameter")
+		t.Logf("WWW-Authenticate header: %s", wwwAuthHeader)
+
+		// Validate WWW-Authenticate header contains scope parameter.
+		require.Contains(t, wwwAuthHeader, `scope="echo sum countdown"`, "WWW-Authenticate header should contain resource_metadata parameter")
 		t.Logf("WWW-Authenticate header: %s", wwwAuthHeader)
 	})
 
@@ -320,7 +325,12 @@ func TestMCPRouteOAuth(t *testing.T) {
 		require.Contains(t, wwwAuthHeader, "Bearer", "WWW-Authenticate header should contain Bearer scheme")
 
 		// Validate WWW-Authenticate header contains resource_metadata parameter.
-		require.Contains(t, wwwAuthHeader, "resource_metadata", "WWW-Authenticate header should contain resource_metadata parameter")
+		require.Contains(t, wwwAuthHeader, `resource_metadata="https://foo.bar.com/.well-known/oauth-protected-resource/mcp"`,
+			"WWW-Authenticate header should contain resource_metadata parameter")
+		t.Logf("WWW-Authenticate header: %s", wwwAuthHeader)
+
+		// Validate WWW-Authenticate header contains scope parameter.
+		require.Contains(t, wwwAuthHeader, `scope="echo sum countdown"`, "WWW-Authenticate header should contain resource_metadata parameter")
 		t.Logf("WWW-Authenticate header: %s", wwwAuthHeader)
 	})
 }