Correctly construct resource_metadata per RFC 9728 Section 3.1 (#2203)

The resource_metadata parameter in WWW-Authenticate header must
contain the full URL to the metadata endpoint, formed by inserting
/.well-known/oauth-protected-resource between the host and path.

Examples:
- Resource: http://localhost:8080
Metadata: http://localhost:8080/.well-known/oauth-protected-resource

- Resource: http://localhost:9090/mcp
Metadata: http://localhost:9090/.well-known/oauth-protected-resource/mcp

This enables clients to discover OAuth metadata for the protected resource.

Fixes #2202

Author: jhrozek

pkg/auth/token.go

@@ -772,8 +772,24 @@ func (v *TokenValidator) buildWWWAuthenticate(includeError bool, errDescription
 	}
 
 	// resource_metadata (RFC 9728)
+	// Per RFC 9728 Section 3.1, the well-known URI is inserted between the host and path components
+	// Example: https://resource.example.com/resource1 -> https://resource.example.com/.well-known/oauth-protected-resource/resource1
 	if v.resourceURL != "" {
-		parts = append(parts, fmt.Sprintf(`resource_metadata="%s"`, EscapeQuotes(v.resourceURL)))
+		parsedURL, err := url.Parse(v.resourceURL)
+		if err == nil {
+			// Per RFC 9728 Section 3.1, remove any terminating slash from path
+			path := parsedURL.Path
+			if path == "/" {
+				path = ""
+			}
+
+			// Construct the metadata URL by inserting the well-known path between host and path
+			metadataURL := fmt.Sprintf("%s://%s/.well-known/oauth-protected-resource%s",
+				parsedURL.Scheme,
+				parsedURL.Host,
+				path)
+			parts = append(parts, fmt.Sprintf(`resource_metadata="%s"`, EscapeQuotes(metadataURL)))
+		}
 	}
 
 	// error fields (RFC 6750 §3)

pkg/auth/token_test.go

@@ -1394,7 +1394,7 @@ func TestBuildWWWAuthenticate_Format(t *testing.T) {
 	t.Parallel()
 	tv := &TokenValidator{
 		issuer:      "https://issuer.example.com",
-		resourceURL: "https://resource.example.com/.well-known/oauth-protected-resource",
+		resourceURL: "https://resource.example.com",
 	}
 	got := tv.buildWWWAuthenticate(true, `failed to parse "token", reason`)
 	want := `Bearer realm="https://issuer.example.com", resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource", error="invalid_token", error_description="failed to parse \"token\", reason"`
@@ -1403,6 +1403,126 @@ func TestBuildWWWAuthenticate_Format(t *testing.T) {
 	}
 }
 
+func TestBuildWWWAuthenticate_ResourceMetadata(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                     string
+		issuer                   string
+		resourceURL              string
+		includeError             bool
+		errDescription           string
+		expectedResourceMetadata string
+	}{
+		{
+			name:                     "resource URL without path",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "http://localhost:8080",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource"`,
+		},
+		{
+			name:                     "resource URL with trailing slash",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "http://localhost:8080/",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource"`,
+		},
+		{
+			name:                     "resource URL with path",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "http://localhost:9090/mcp",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="http://localhost:9090/.well-known/oauth-protected-resource/mcp"`,
+		},
+		{
+			name:                     "resource URL with path and trailing slash",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "http://localhost:9090/mcp/",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="http://localhost:9090/.well-known/oauth-protected-resource/mcp/"`,
+		},
+		{
+			name:                     "resource URL with nested path",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "https://api.example.com/v1/mcp",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/v1/mcp"`,
+		},
+		{
+			name:                     "resource URL with HTTPS",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "https://resource.example.com",
+			includeError:             false,
+			expectedResourceMetadata: `resource_metadata="https://resource.example.com/.well-known/oauth-protected-resource"`,
+		},
+		{
+			name:                     "empty resource URL",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "",
+			includeError:             false,
+			expectedResourceMetadata: "",
+		},
+		{
+			name:                     "with error and description",
+			issuer:                   "https://issuer.example.com",
+			resourceURL:              "http://localhost:8080",
+			includeError:             true,
+			errDescription:           "token expired",
+			expectedResourceMetadata: `resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource"`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			tv := &TokenValidator{
+				issuer:      tt.issuer,
+				resourceURL: tt.resourceURL,
+			}
+
+			got := tv.buildWWWAuthenticate(tt.includeError, tt.errDescription)
+
+			// Check that it starts with "Bearer "
+			if !strings.HasPrefix(got, "Bearer ") {
+				t.Errorf("Expected header to start with 'Bearer ', got: %s", got)
+			}
+
+			// Check realm is present
+			if tt.issuer != "" && !strings.Contains(got, fmt.Sprintf(`realm="%s"`, tt.issuer)) {
+				t.Errorf("Expected realm to be present in: %s", got)
+			}
+
+			// Check resource_metadata
+			if tt.expectedResourceMetadata != "" {
+				if !strings.Contains(got, tt.expectedResourceMetadata) {
+					t.Errorf("Expected resource_metadata:\n  %s\nto be in:\n  %s", tt.expectedResourceMetadata, got)
+				}
+			} else if tt.resourceURL == "" {
+				// If resource URL is empty, resource_metadata should not be present
+				if strings.Contains(got, "resource_metadata") {
+					t.Errorf("Expected no resource_metadata in: %s", got)
+				}
+			}
+
+			// Check error fields
+			if tt.includeError {
+				if !strings.Contains(got, `error="invalid_token"`) {
+					t.Errorf("Expected error field in: %s", got)
+				}
+				if tt.errDescription != "" && !strings.Contains(got, fmt.Sprintf(`error_description="%s"`, tt.errDescription)) {
+					t.Errorf("Expected error_description in: %s", got)
+				}
+			} else {
+				if strings.Contains(got, "error=") {
+					t.Errorf("Expected no error field in: %s", got)
+				}
+			}
+		})
+	}
+}
+
 func TestIntrospectGoogleToken(t *testing.T) {
 	t.Parallel()