auth: add Scopes allowlist to AuthorizationCodeHandlerConfig

The authorization-code handler requests every scope advertised in the
protected resource's metadata (or named in the WWW-Authenticate challenge),
with no way for a client to narrow that set. Some servers advertise a scope a
client should not request: Gmail's MCP server lists gmail.metadata, and the
Gmail API refuses the search "q" parameter on any token carrying gmail.metadata
even when gmail.readonly is also granted.

Add an optional Scopes field that, when non-empty, intersects the discovered
scopes with the allowlist (order preserved). An empty intersection is ignored
so a misconfigured allowlist never leaves the client requesting no scopes;
offline_access is applied after filtering and so is unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: toabctl

auth/authorization_code.go

@@ -97,6 +97,19 @@ type AuthorizationCodeHandlerConfig struct {
 	// See [AuthorizationCodeFetcher] for details.
 	AuthorizationCodeFetcher AuthorizationCodeFetcher
 
+	// Scopes optionally restricts the OAuth scopes requested during
+	// authorization to this allowlist. By default the handler requests every
+	// scope advertised in the protected resource's metadata (or named in the
+	// WWW-Authenticate challenge); when Scopes is non-empty the requested set is
+	// intersected with it, preserving discovery order. This lets a client avoid
+	// an advertised scope it does not want — for example Gmail's gmail.metadata
+	// scope, which the Gmail API refuses to combine with the search "q"
+	// parameter even when gmail.readonly is also granted. An allowlist that
+	// matches none of the advertised scopes is ignored, so the flow never
+	// requests an empty scope set; offline_access (see RequestRefreshToken) is
+	// exempt from filtering.
+	Scopes []string
+
 	// RequestRefreshToken indicates that the client intends to use refresh
 	// tokens and is capable of storing them securely.
 	//
@@ -293,6 +306,13 @@ func (h *AuthorizationCodeHandler) Authorize(ctx context.Context, req *http.Requ
 		requestedScopes = prm.ScopesSupported
 	}
 
+	// Restrict the discovered scopes to the configured allowlist, if any, so a
+	// client can avoid an advertised scope it does not want. Applied before the
+	// offline_access and step-up union logic below so neither is affected.
+	if len(h.config.Scopes) > 0 {
+		requestedScopes = intersectScopes(requestedScopes, h.config.Scopes)
+	}
+
 	// SEP-2207: when the client desires refresh tokens and the Authorization
 	// Server advertises offline_access support, add it to the requested scopes.
 	if h.config.RequestRefreshToken &&
@@ -358,6 +378,23 @@ func scopesFromChallenges(cs []oauthex.Challenge) []string {
 	return nil
 }
 
+// intersectScopes returns the members of scopes that also appear in allow,
+// preserving the order of scopes. If nothing matches it returns scopes
+// unchanged, so a misconfigured allowlist cannot leave the client requesting no
+// scopes at all.
+func intersectScopes(scopes, allow []string) []string {
+	keep := make([]string, 0, len(scopes))
+	for _, s := range scopes {
+		if slices.Contains(allow, s) {
+			keep = append(keep, s)
+		}
+	}
+	if len(keep) == 0 {
+		return scopes
+	}
+	return keep
+}
+
 // errorFromChallenges returns the error from the given "WWW-Authenticate" header challenges.
 // It only looks at challenges with the "Bearer" scheme.
 func errorFromChallenges(cs []oauthex.Challenge) string {

auth/authorization_code_test.go

@@ -1222,6 +1222,99 @@ func TestAuthorize_OfflineAccessScope(t *testing.T) {
 	}
 }
 
+func TestAuthorize_ScopesAllowlist(t *testing.T) {
+	// advertised is delivered via the WWW-Authenticate "scope" challenge, which
+	// the handler treats as the requested scopes before applying the allowlist.
+	const advertised = "gmail.metadata gmail.readonly gmail.compose"
+	tests := []struct {
+		name       string
+		allowlist  []string
+		wantScopes string
+	}{
+		{
+			name:       "FiltersToAllowlistPreservingOrder",
+			allowlist:  []string{"gmail.compose", "gmail.readonly"},
+			wantScopes: "gmail.readonly gmail.compose",
+		},
+		{
+			name:       "EmptyIntersectionFailsOpen",
+			allowlist:  []string{"drive.readonly"},
+			wantScopes: advertised,
+		},
+		{
+			name:       "NoAllowlistLeavesScopesUnchanged",
+			allowlist:  nil,
+			wantScopes: advertised,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			authServer := oauthtest.NewFakeAuthorizationServer(oauthtest.Config{
+				RegistrationConfig: &oauthtest.RegistrationConfig{
+					PreregisteredClients: map[string]oauthtest.ClientInfo{
+						"test_client_id": {
+							Secret:       "test_client_secret",
+							RedirectURIs: []string{"http://localhost:12345/callback"},
+						},
+					},
+				},
+			})
+			authServer.Start(t)
+
+			resourceMux := http.NewServeMux()
+			resourceServer := httptest.NewServer(resourceMux)
+			t.Cleanup(resourceServer.Close)
+			resourceURL := resourceServer.URL + "/resource"
+			resourceMux.Handle("/.well-known/oauth-protected-resource/resource", ProtectedResourceMetadataHandler(&oauthex.ProtectedResourceMetadata{
+				Resource:             resourceURL,
+				AuthorizationServers: []string{authServer.URL()},
+			}))
+
+			var capturedAuthURL string
+			handler, err := NewAuthorizationCodeHandler(&AuthorizationCodeHandlerConfig{
+				RedirectURL: "http://localhost:12345/callback",
+				PreregisteredClient: &oauthex.ClientCredentials{
+					ClientID:         "test_client_id",
+					ClientSecretAuth: &oauthex.ClientSecretAuth{ClientSecret: "test_client_secret"},
+				},
+				Scopes: tt.allowlist,
+				AuthorizationCodeFetcher: func(ctx context.Context, args *AuthorizationArgs) (*AuthorizationResult, error) {
+					capturedAuthURL = args.URL
+					return nil, fmt.Errorf("stop after capturing URL")
+				},
+			})
+			if err != nil {
+				t.Fatalf("NewAuthorizationCodeHandler failed: %v", err)
+			}
+
+			req := httptest.NewRequest(http.MethodGet, resourceURL, nil)
+			resp := &http.Response{
+				StatusCode: http.StatusUnauthorized,
+				Header:     make(http.Header),
+				Body:       http.NoBody,
+				Request:    req,
+			}
+			resp.Header.Set("WWW-Authenticate", fmt.Sprintf(
+				"Bearer resource_metadata=%s/.well-known/oauth-protected-resource/resource, scope=%q",
+				resourceServer.URL, advertised))
+
+			handler.Authorize(context.Background(), req, resp)
+
+			if capturedAuthURL == "" {
+				t.Fatal("AuthorizationCodeFetcher was not called")
+			}
+			u, err := url.Parse(capturedAuthURL)
+			if err != nil {
+				t.Fatalf("failed to parse captured auth URL: %v", err)
+			}
+			if got := u.Query().Get("scope"); got != tt.wantScopes {
+				t.Errorf("requested scope = %q, want %q", got, tt.wantScopes)
+			}
+		})
+	}
+}
+
 // validConfig for test to create an AuthorizationCodeHandler using its constructor.
 // Values that are relevant to the test should be set explicitly.
 func validConfig() *AuthorizationCodeHandlerConfig {