feat(auth): support manual PRM override (#2717)

Add flag to allow manual PRM override.

Author: duwenxin99

cmd/internal/flags.go

@@ -65,6 +65,7 @@ func ServeFlags(flags *pflag.FlagSet, opts *ToolboxOptions) {
 	flags.BoolVar(&opts.Cfg.UI, "ui", false, "Launches the Toolbox UI web server.")
 	flags.BoolVar(&opts.Cfg.EnableAPI, "enable-api", false, "Enable the /api endpoint.")
 	flags.StringVar(&opts.Cfg.ToolboxUrl, "toolbox-url", "", "Specifies the Toolbox URL. Used as the resource field in the MCP PRM file when MCP Auth is enabled. Falls back to TOOLBOX_URL environment variable.")
+	flags.StringVar(&opts.Cfg.McpPrmFile, "mcp-prm-file", "", "Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation.")
 	flags.StringSliceVar(&opts.Cfg.AllowedOrigins, "allowed-origins", []string{"*"}, "Specifies a list of origins permitted to access this server. Defaults to '*'.")
 	flags.StringSliceVar(&opts.Cfg.AllowedHosts, "allowed-hosts", []string{"*"}, "Specifies a list of hosts permitted to access this server. Defaults to '*'.")
 }

docs/en/reference/cli.md

@@ -15,6 +15,7 @@ description: >
 | `-h`         | `--help`                   | help for toolbox                                                                                                                                                                 |             |
 |              | `--log-level`              | Specify the minimum level logged. Allowed: 'DEBUG', 'INFO', 'WARN', 'ERROR'.                                                                                                     | `info`      |
 |              | `--logging-format`         | Specify logging format to use. Allowed: 'standard' or 'JSON'.                                                                                                                    | `standard`  |
+|              | `--mcp-prm-file`           | Path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation for MCP Server-Wide Authentication.                                         |             |
 | `-p`         | `--port`                   | Port the server will listen on.                                                                                                                                                  | `5000`      |
 |              | `--prebuilt`               | Use one or more prebuilt tool configuration by source type. See [Prebuilt Tools Reference](../documentation/configuration/prebuilt-configs/_index.md) for allowed values.                                                |             |
 |              | `--stdio`                  | Listens via MCP STDIO instead of acting as a remote HTTP server.                                                                                                                 |             |

internal/server/config.go

@@ -74,6 +74,8 @@ type ServerConfig struct {
 	EnableAPI bool
 	// ToolboxUrl specifies the URL to advertise in the MCP PRM file as the resource field.
 	ToolboxUrl string
+	// McpPrmFile specifies the path to a manual Protected Resource Metadata (PRM) JSON file. If provided, overrides auto-generation.
+	McpPrmFile string
 	// Specifies a list of origins permitted to access this server.
 	AllowedOrigins []string
 	// Specifies a list of hosts permitted to access this server.

internal/server/prm.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package server
+
+// ProtectedResourceMetadata represents the OAuth 2.0 Protected Resource Metadata document as defined in RFC 9728.
+// Reference: https://datatracker.ietf.org/doc/html/rfc9728
+type ProtectedResourceMetadata struct {
+	// REQUIRED. The protected resource's resource identifier (a URL using the https scheme).
+	Resource string `json:"resource"`
+
+	// REQUIRED. Array containing a list of OAuth authorization server issuer identifiers.
+	AuthorizationServers []string `json:"authorization_servers,omitempty"`
+
+	// OPTIONAL. URL of the protected resource's JSON Web Key (JWK) Set document.
+	JWKSURI string `json:"jwks_uri,omitempty"`
+
+	// RECOMMENDED. Array containing a list of scope values used to request access.
+	ScopesSupported []string `json:"scopes_supported,omitempty"`
+
+	// OPTIONAL. Array containing a list of the supported methods of sending an
+	// OAuth 2.0 bearer token (e.g., "header", "body", "query").
+	BearerMethodsSupported []string `json:"bearer_methods_supported,omitempty"`
+
+	// OPTIONAL. Array containing a list of the JWS signing algorithms (alg values)
+	// supported by the protected resource for signing resource responses.
+	ResourceSigningAlgValuesSupported []string `json:"resource_signing_alg_values_supported,omitempty"`
+
+	// RECOMMENDED. Human-readable name of the protected resource intended for display.
+	ResourceName string `json:"resource_name,omitempty"`
+
+	// OPTIONAL. URL of a page containing human-readable developer documentation.
+	ResourceDocumentation string `json:"resource_documentation,omitempty"`
+
+	// OPTIONAL. URL of a page containing human-readable policy requirements.
+	ResourcePolicyURI string `json:"resource_policy_uri,omitempty"`
+
+	// OPTIONAL. URL of a page containing human-readable terms of service.
+	ResourceTOSURI string `json:"resource_tos_uri,omitempty"`
+
+	// OPTIONAL. Boolean indicating support for mutual-TLS client certificate-bound
+	// access tokens. If omitted, the default is false.
+	TLSClientCertificateBoundAccessTokens *bool `json:"tls_client_certificate_bound_access_tokens,omitempty"`
+
+	// OPTIONAL. Array containing a list of authorization details type values supported.
+	AuthorizationDetailsTypesSupported []string `json:"authorization_details_types_supported,omitempty"`
+
+	// OPTIONAL. Array containing a list of JWS alg values supported for DPoP proof JWTs.
+	DPoPSigningAlgValuesSupported []string `json:"dpop_signing_alg_values_supported,omitempty"`
+
+	// OPTIONAL. Boolean specifying whether the protected resource always requires
+	// the use of DPoP-bound access tokens. If omitted, the default is false.
+	DPoPBoundAccessTokensRequired *bool `json:"dpop_bound_access_tokens_required,omitempty"`
+
+	// OPTIONAL. A JWT containing metadata parameters about the protected resource
+	// as claims. Consists of the entire signed JWT string.
+	SignedMetadata string `json:"signed_metadata,omitempty"`
+}

internal/server/server.go

@@ -16,11 +16,13 @@ package server
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"net"
 	"net/http"
+	"os"
 	"slices"
 	"strconv"
 	"strings"
@@ -55,6 +57,7 @@ type Server struct {
 	instrumentation *telemetry.Instrumentation
 	sseManager      *sseManager
 	ResourceMgr     *resources.ResourceManager
+	mcpPrmFile      string
 }
 
 func InitializeConfigs(ctx context.Context, cfg ServerConfig) (
@@ -382,6 +385,7 @@ func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error) {
 		sseManager:      sseManager,
 		ResourceMgr:     resourceManager,
 		toolboxUrl:      cfg.ToolboxUrl,
+		mcpPrmFile:      cfg.McpPrmFile,
 	}
 
 	// cors
@@ -419,8 +423,35 @@ func NewServer(ctx context.Context, cfg ServerConfig) (*Server, error) {
 			break
 		}
 	}
-	if mcpAuthEnabled {
+
+	// Manual PRM override
+	var cachedPrmBytes []byte
+	var prmConfig ProtectedResourceMetadata
+	if s.mcpPrmFile != "" {
+		var err error
+		cachedPrmBytes, err = os.ReadFile(s.mcpPrmFile)
+		if err != nil {
+			return nil, fmt.Errorf("failed to read manual PRM file at startup: %w", err)
+		}
+		// Unmarshal into the struct to strictly validate the schema
+		if err := json.Unmarshal(cachedPrmBytes, &prmConfig); err != nil {
+			return nil, fmt.Errorf("manual PRM file does not match expected schema: %w", err)
+		}
+	}
+
+	// Register route if auth is enabled or a manual file is provided
+	if mcpAuthEnabled || s.mcpPrmFile != "" {
 		r.Get("/.well-known/oauth-protected-resource", func(w http.ResponseWriter, req *http.Request) {
+			// Serve from memory if file was loaded
+			if s.mcpPrmFile != "" {
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(http.StatusOK)
+				if _, err := w.Write(cachedPrmBytes); err != nil {
+					s.logger.ErrorContext(req.Context(), "failed to write manual PRM file response", "error", err)
+				}
+				return
+			}
+
 			prmHandler(s, w, req)
 		})
 	}

internal/server/server_test.go

@@ -384,3 +384,95 @@ func TestPRMEndpoint(t *testing.T) {
 		t.Errorf("unexpected PRM response:\ngot  %+v\nwant %+v", got, want)
 	}
 }
+
+func TestPRMOverride(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	// Setup a temporary PRM file
+	prmContent := `{
+		"resource": "https://override.example.com",
+		"authorization_servers": ["https://auth.example.com"],
+		"scopes_supported": ["read", "write"],
+		"bearer_methods_supported": ["header"]
+	}`
+	tmpFile, err := os.CreateTemp("", "prm-*.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(tmpFile.Name())
+	if err := os.WriteFile(tmpFile.Name(), []byte(prmContent), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	// Setup Logging and Instrumentation (Using Discard to act as Noop)
+	testLogger, err := log.NewStdLogger(io.Discard, io.Discard, "info")
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	ctx = util.WithLogger(ctx, testLogger)
+
+	instrumentation, err := telemetry.CreateTelemetryInstrumentation("0.0.0")
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	ctx = util.WithInstrumentation(ctx, instrumentation)
+
+	// Configure the server with the Override Flag
+	addr, port := "127.0.0.1", 5002
+	cfg := server.ServerConfig{
+		Version:      "0.0.0",
+		Address:      addr,
+		Port:         port,
+		McpPrmFile:   tmpFile.Name(),
+		AllowedHosts: []string{"*"},
+	}
+
+	// Initialize and Start the Server
+	s, err := server.NewServer(ctx, cfg)
+	if err != nil {
+		t.Fatalf("unable to initialize server: %v", err)
+	}
+
+	if err := s.Listen(ctx); err != nil {
+		t.Fatalf("unable to start listener: %v", err)
+	}
+
+	go func() {
+		if err := s.Serve(ctx); err != nil && err != http.ErrServerClosed {
+			fmt.Printf("Server serve error: %v\n", err)
+		}
+	}()
+	defer func() {
+		if err := s.Shutdown(ctx); err != nil {
+			t.Errorf("failed to cleanly shutdown server: %v", err)
+		}
+	}()
+
+	// Perform the request to the well-known endpoint
+	url := fmt.Sprintf("http://%s:%d/.well-known/oauth-protected-resource", addr, port)
+	resp, err := http.Get(url)
+	if err != nil {
+		t.Fatalf("error when sending request: %s", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected status 200, got %d", resp.StatusCode)
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("error reading body: %s", err)
+	}
+
+	// Verification
+	var got map[string]any
+	if err := json.Unmarshal(body, &got); err != nil {
+		t.Fatalf("invalid json response: %s", err)
+	}
+
+	if got["resource"] != "https://override.example.com" {
+		t.Errorf("expected resource 'https://override.example.com', got '%v'", got["resource"])
+	}
+}