add missing scopes in the response header

Signed-off-by: Huabing Zhao <[email protected]>

Author: zhaohuabing

internal/controller/gateway.go

@@ -476,6 +476,10 @@ func mcpConfig(mcpRoutes []aigv1a1.MCPRoute) *filterapi.MCPConfig {
 			authorization := route.Spec.SecurityPolicy.Authorization
 			mcpRoute.Authorization = &filterapi.MCPRouteAuthorization{}
 
+			if route.Spec.SecurityPolicy.OAuth != nil {
+				mcpRoute.Authorization.ResourceMetadataURL = buildResourceMetadataURL(&route.Spec.SecurityPolicy.OAuth.ProtectedResourceMetadata)
+			}
+
 			for _, rule := range authorization.Rules {
 				scopes := make([]string, len(rule.Source.JWTSource.Scopes))
 				for i, scope := range rule.Source.JWTSource.Scopes {

internal/controller/mcp_route_security_policy.go

@@ -281,13 +281,11 @@ func (c *MCPRouteController) ensureOAuthProtectedResourceMetadataBTP(ctx context
 	return nil
 }
 
-// buildWWWAuthenticateHeaderValue constructs the WWW-Authenticate header value according to RFC 9728.
+// buildResourceMetadataURL constructs the OAuth protected resource metadata URL using the resource identifier.
 // References:
 // * https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location
 // * https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response
-func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata) string {
-	// Build resource metadata URL using RFC 8414 compliant pattern.
-	// Extract base URL and path from resource identifier.
+func buildResourceMetadataURL(metadata *aigv1a1.ProtectedResourceMetadata) string {
 	resourceURL := strings.TrimSuffix(metadata.Resource, "/")
 
 	var (
@@ -316,7 +314,15 @@ func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata
 	// they should honor hte value returned here.
 	// We can't expose these resource at the root, because there may be multiple MCP routes with different OAuth settings, so we need
 	// to rely on clients properly implementing the spec and using this value returned in the header.
-	resourceMetadataURL := fmt.Sprintf("%s%s%s", baseURL, oauthWellKnownProtectedResourceMetadataPath, pathComponent)
+	return fmt.Sprintf("%s%s%s", baseURL, oauthWellKnownProtectedResourceMetadataPath, pathComponent)
+}
+
+// buildWWWAuthenticateHeaderValue constructs the WWW-Authenticate header value according to RFC 9728.
+// References:
+// * https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location
+// * https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response
+func buildWWWAuthenticateHeaderValue(metadata *aigv1a1.ProtectedResourceMetadata) string {
+	resourceMetadataURL := buildResourceMetadataURL(metadata)
 	// Build the basic Bearer challenge.
 	headerValue := `Bearer error="invalid_request", error_description="No access token was provided in this request"`
 

internal/filterapi/mcpconfig.go

@@ -65,9 +65,14 @@ type MCPRouteName = string
 // MCPRouteAuthorization defines the authorization configuration for a MCPRoute.
 type MCPRouteAuthorization struct {
 	// Rules defines a list of authorization rules.
-	// These rules are evaluated in order, the first matching rule will be applied,
-	// and the rest will be skipped.
+	// Requests that match any rule and satisfy the rule's conditions will be allowed.
+	// Requests that do not match any rule or fail to satisfy the matched rule's conditions will be denied.
+	// If no rules are defined, all requests will be denied.
 	Rules []MCPRouteAuthorizationRule `json:"rules,omitempty"`
+
+	// ResourceMetadataURL is the URI of the OAuth Protected Resource Metadata document for this route.
+	// This is used to populate the WWW-Authenticate header when scope-based authorization fails.
+	ResourceMetadataURL string `json:"resourceMetadataURL,omitempty"`
 }
 
 // MCPRouteAuthorizationRule defines an authorization rule for MCPRoute based on the MCP authorization spec.

internal/mcpproxy/authorization.go

@@ -8,6 +8,7 @@ package mcpproxy
 import (
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log/slog"
 	"net/http"
 	"regexp"
@@ -20,14 +21,15 @@ import (
 )
 
 // authorizeRequest authorizes the request based on the given MCPRouteAuthorization configuration.
-func (m *MCPProxy) authorizeRequest(authorization *filterapi.MCPRouteAuthorization, headers http.Header, backendName, toolName string, argments any) bool {
+
+func (m *MCPProxy) authorizeRequest(authorization *filterapi.MCPRouteAuthorization, headers http.Header, backendName, toolName string, argments any) (bool, []string) {
 	if authorization == nil {
-		return true
+		return true, nil
 	}
 
 	// If no rules are defined, deny all requests.
 	if len(authorization.Rules) == 0 {
-		return false
+		return false, nil
 	}
 
 	// If the rules are defined, a valid bearer token is required.
@@ -36,17 +38,18 @@ func (m *MCPProxy) authorizeRequest(authorization *filterapi.MCPRouteAuthorizati
 	// should always be present and valid.
 	if err != nil {
 		m.l.Info("missing or invalid bearer token", slog.String("error", err.Error()))
-		return false
+		return false, nil
 	}
 
 	claims := jwt.MapClaims{}
 	// JWT verification is performed by Envoy before reaching here. So we only need to parse the token without verification.
 	if _, _, err := jwt.NewParser().ParseUnverified(token, claims); err != nil {
 		m.l.Info("failed to parse JWT token", slog.String("error", err.Error()))
-		return false
+		return false, nil
 	}
 
 	scopeSet := sets.New[string](extractScopes(claims)...)
+	var missingScopesForChallenge []string
 
 	for _, rule := range authorization.Rules {
 		var args map[string]any
@@ -58,12 +61,19 @@ func (m *MCPProxy) authorizeRequest(authorization *filterapi.MCPRouteAuthorizati
 		if !m.toolMatches(filterapi.ToolCall{BackendName: backendName, ToolName: toolName}, rule.Target.Tools, args) {
 			continue
 		}
-		if scopesSatisfied(scopeSet, rule.Source.JWTSource.Scopes) {
-			return true
+
+		requiredScopes := rule.Source.JWTSource.Scopes
+		if scopesSatisfied(scopeSet, requiredScopes) {
+			return true, nil
+		}
+
+		// Keep track of the smallest set of missing scopes for challenge.
+		if len(missingScopesForChallenge) == 0 || len(requiredScopes) < len(missingScopesForChallenge) {
+			missingScopesForChallenge = requiredScopes
 		}
 	}
 
-	return false
+	return false, missingScopesForChallenge
 }
 
 func bearerToken(header string) (string, error) {
@@ -172,3 +182,16 @@ func scopesSatisfied(have sets.Set[string], required []string) bool {
 	}
 	return true
 }
+
+// buildInsufficientScopeHeader builds the WWW-Authenticate header value for insufficient scope errors.
+// Reference: https://mcp.mintlify.app/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors
+func buildInsufficientScopeHeader(scopes []string, resourceMetadata string) string {
+	parts := []string{`Bearer error="insufficient_scope"`}
+	parts = append(parts, fmt.Sprintf(`scope="%s"`, strings.Join(scopes, " ")))
+	if resourceMetadata != "" {
+		parts = append(parts, fmt.Sprintf(`resource_metadata="%s"`, resourceMetadata))
+	}
+	parts = append(parts, `error_description="The token is missing required scopes"`)
+
+	return strings.Join(parts, ", ")
+}

internal/mcpproxy/authorization_test.go

@@ -9,6 +9,7 @@ import (
 	"io"
 	"log/slog"
 	"net/http"
+	"reflect"
 	"testing"
 
 	"github.com/golang-jwt/jwt/v5"
@@ -38,6 +39,7 @@ func TestAuthorizeRequest(t *testing.T) {
 		toolName      string
 		args          map[string]any
 		expectAllowed bool
+		expectScopes  []string
 	}{
 		{
 			name: "matching tool and scope",
@@ -57,6 +59,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "tool1",
 			expectAllowed: true,
+			expectScopes:  nil,
 		},
 		{
 			name: "matching tool scope and arguments regex",
@@ -89,6 +92,7 @@ func TestAuthorizeRequest(t *testing.T) {
 				"debug": "true",
 			},
 			expectAllowed: true,
+			expectScopes:  nil,
 		},
 		{
 			name: "numeric argument matches via JSON string",
@@ -115,6 +119,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			toolName:      "tool1",
 			args:          map[string]any{"count": 42},
 			expectAllowed: true,
+			expectScopes:  nil,
 		},
 		{
 			name: "object argument can be matched via JSON string",
@@ -149,6 +154,7 @@ func TestAuthorizeRequest(t *testing.T) {
 				},
 			},
 			expectAllowed: true,
+			expectScopes:  nil,
 		},
 		{
 			name: "matching tool but insufficient scopes not allowed",
@@ -168,6 +174,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "tool1",
 			expectAllowed: false,
+			expectScopes:  []string{"read", "write"},
 		},
 		{
 			name: "argument regex mismatch denied",
@@ -196,6 +203,7 @@ func TestAuthorizeRequest(t *testing.T) {
 				"mode": "other",
 			},
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name: "missing argument denies when required",
@@ -222,6 +230,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			toolName:      "tool1",
 			args:          map[string]any{},
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name: "no matching rule falls back to default deny - tool mismatch",
@@ -241,6 +250,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "other-tool",
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name: "no matching rule falls back to default deny - scope mismatch",
@@ -260,6 +270,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "other-tool",
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name:          "no rules falls back to default deny",
@@ -268,6 +279,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "tool1",
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name: "no bearer token not allowed when rules exist",
@@ -287,6 +299,7 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "tool1",
 			expectAllowed: false,
+			expectScopes:  nil,
 		},
 		{
 			name: "invalid bearer token not allowed when rules exist",
@@ -306,6 +319,27 @@ func TestAuthorizeRequest(t *testing.T) {
 			backendName:   "backend1",
 			toolName:      "tool1",
 			expectAllowed: false,
+			expectScopes:  nil,
+		},
+		{
+			name: "selects smallest required scope set when multiple rules match",
+			auth: &filterapi.MCPRouteAuthorization{
+				Rules: []filterapi.MCPRouteAuthorizationRule{
+					{
+						Source: filterapi.MCPAuthorizationSource{JWTSource: filterapi.JWTSource{Scopes: []string{"alpha", "beta", "gamma"}}},
+						Target: filterapi.MCPAuthorizationTarget{Tools: []filterapi.ToolCall{{BackendName: "backend1", ToolName: "tool1"}}},
+					},
+					{
+						Source: filterapi.MCPAuthorizationSource{JWTSource: filterapi.JWTSource{Scopes: []string{"alpha", "beta"}}},
+						Target: filterapi.MCPAuthorizationTarget{Tools: []filterapi.ToolCall{{BackendName: "backend1", ToolName: "tool1"}}},
+					},
+				},
+			},
+			header:        "Bearer " + makeToken("alpha"),
+			backendName:   "backend1",
+			toolName:      "tool1",
+			expectAllowed: false,
+			expectScopes:  []string{"alpha", "beta"},
 		},
 	}
 
@@ -315,10 +349,25 @@ func TestAuthorizeRequest(t *testing.T) {
 			if tt.header != "" {
 				headers.Set("Authorization", tt.header)
 			}
-			allowed := proxy.authorizeRequest(tt.auth, headers, tt.backendName, tt.toolName, tt.args)
+			allowed, requiredScopes := proxy.authorizeRequest(tt.auth, headers, tt.backendName, tt.toolName, tt.args)
 			if allowed != tt.expectAllowed {
 				t.Fatalf("expected %v, got %v", tt.expectAllowed, allowed)
 			}
+			if !reflect.DeepEqual(requiredScopes, tt.expectScopes) {
+				t.Fatalf("expected required scopes %v, got %v", tt.expectScopes, requiredScopes)
+			}
 		})
 	}
 }
+
+func TestBuildInsufficientScopeHeader(t *testing.T) {
+	const resourceMetadata = "https://api.example.com/.well-known/oauth-protected-resource/mcp"
+
+	t.Run("with scopes and resource metadata", func(t *testing.T) {
+		header := buildInsufficientScopeHeader([]string{"read", "write"}, resourceMetadata)
+		expected := `Bearer error="insufficient_scope", scope="read write", resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", error_description="The token is missing required scopes"`
+		if header != expected {
+			t.Fatalf("expected %q, got %q", expected, header)
+		}
+	})
+}

internal/mcpproxy/handlers.go

@@ -542,7 +542,15 @@ func (m *MCPProxy) handleToolCallRequest(ctx context.Context, s *session, w http
 
 	// Enforce authentication if required by the route.
 	if route.authorization != nil {
-		if !m.authorizeRequest(route.authorization, headers, backendName, toolName, p.Arguments) {
+		allowed, requiredScopes := m.authorizeRequest(route.authorization, headers, backendName, toolName, p.Arguments)
+		if !allowed {
+			// Specify the minimum required scopes in the WWW-Authenticate header.
+			// Reference: https://mcp.mintlify.app/specification/2025-11-25/basic/authorization#runtime-insufficient-scope-errors
+			if len(requiredScopes) > 0 {
+				if challenge := buildInsufficientScopeHeader(requiredScopes, route.authorization.ResourceMetadataURL); challenge != "" {
+					w.Header().Set("WWW-Authenticate", challenge)
+				}
+			}
 			onErrorResponse(w, http.StatusForbidden, "authorization failed")
 			return fmt.Errorf("authorization failed")
 		}

tests/crdcel/testdata/mcpgatewayroutes/authorization_without_oauth.yaml

@@ -19,7 +19,6 @@ spec:
       port: 80
   securityPolicy:
     authorization:
-      defaultAction: Deny
       rules:
         - source:
             jwtSource:
@@ -29,4 +28,3 @@ spec:
             tools:
               - backendName: mcp-service
                 toolName: echo
-          action: Allow

tests/e2e/mcp_route_authorization_test.go

@@ -6,6 +6,7 @@
 package e2e
 
 import (
+	"bytes"
 	"context"
 	"crypto/rsa"
 	"encoding/base64"
@@ -167,6 +168,46 @@ func TestMCPRouteAuthorization(t *testing.T) {
 		errMsg := strings.ToLower(err.Error())
 		require.True(t, strings.Contains(errMsg, "403") || strings.Contains(errMsg, "authorization"), "unexpected error: %v", err)
 	})
+
+	t.Run("WWW-Authenticate on insufficient scope", func(t *testing.T) {
+		token := makeSignedJWT(t, "sum") // only sum scope; echo requires echo
+		authHTTPClient := &http.Client{
+			Timeout: 10 * time.Second,
+			Transport: &bearerTokenTransport{
+				token: token,
+			},
+		}
+
+		routeHeader := "default/mcp-route-authorization-default-deny"
+
+		// First, initialize a session to obtain a session ID header.
+		ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
+		t.Cleanup(cancel)
+
+		sess := requireConnectMCP(ctx, t, client, fmt.Sprintf("%s/mcp-authorization", fwd.Address()), authHTTPClient)
+		t.Cleanup(func() {
+			_ = sess.Close()
+		})
+
+		// Now call a tool that requires a missing scope to trigger insufficient_scope.
+		reqBody := []byte(`{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"mcp-backend-authorization__echo","arguments":{"text":"Hello, world!"}}}`)
+		req, err := http.NewRequest(http.MethodPost, fmt.Sprintf("%s/mcp-authorization", fwd.Address()), bytes.NewReader(reqBody))
+		require.NoError(t, err)
+		req.Header.Set("Authorization", "Bearer "+token)
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("mcp-session-id", sess.ID())
+		req.Header.Set("x-ai-eg-mcp-route", routeHeader)
+
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer resp.Body.Close()
+
+		require.Equal(t, http.StatusForbidden, resp.StatusCode)
+		wwwAuth := resp.Header.Get("WWW-Authenticate")
+		require.Contains(t, wwwAuth, `error="insufficient_scope"`)
+		require.Contains(t, wwwAuth, `scope="echo"`) // expected missing scope
+		require.Contains(t, wwwAuth, `resource_metadata="https://foo.bar.com/.well-known/oauth-protected-resource/mcp"`)
+	})
 }
 
 func requireConnectMCP(ctx context.Context, t *testing.T, client *mcp.Client, endpoint string, httpClient *http.Client) *mcp.ClientSession {