Add --remote-auth-scope-param-name flag for non-standard OAuth scope parameters

Some OAuth providers use non-standard query parameter names for scopes
in the authorization URL. For example, Slack's OAuth v2 requires
user-token scopes in "user_scope" instead of the standard "scope"
parameter. This causes ToolHive's OAuth flow to fail with invalid_scope
errors when connecting to providers like Slack's MCP server.

Add a new --remote-auth-scope-param-name flag that allows users to
override the query parameter name used for scopes. When set, scopes are
sent under the specified parameter name and the standard "scope"
parameter is cleared. The oauth2Config.Scopes field is preserved so
token refresh requests continue to work correctly.

Signed-off-by: Gustavo Gomez <gmogmz@indeed.com>

Author: gmogmzGithub

cmd/thv/app/auth_flags.go

@@ -72,6 +72,7 @@ type RemoteAuthFlags struct {
 	RemoteAuthClientSecret     string
 	RemoteAuthClientSecretFile string
 	RemoteAuthScopes           []string
+	RemoteAuthScopeParamName   string
 	RemoteAuthSkipBrowser      bool
 	RemoteAuthTimeout          time.Duration
 	RemoteAuthCallbackPort     int
@@ -163,6 +164,8 @@ func AddRemoteAuthFlags(cmd *cobra.Command, config *RemoteAuthFlags) {
 			"authorization server supports dynamic client registration (RFC 7591) or if using PKCE)")
 	cmd.Flags().StringSliceVar(&config.RemoteAuthScopes, "remote-auth-scopes", []string{},
 		"OAuth scopes to request for remote server authentication (defaults: OIDC uses 'openid,profile,email')")
+	cmd.Flags().StringVar(&config.RemoteAuthScopeParamName, "remote-auth-scope-param-name", "",
+		"Override the query parameter name for scopes in the authorization URL (e.g., 'user_scope' for Slack OAuth)")
 	cmd.Flags().BoolVar(&config.RemoteAuthSkipBrowser, "remote-auth-skip-browser", false,
 		"Skip opening browser for remote server OAuth flow (default false)")
 	cmd.Flags().DurationVar(&config.RemoteAuthTimeout, "remote-auth-timeout", 30*time.Second,

cmd/thv/app/proxy.go

@@ -360,14 +360,15 @@ func handleOutgoingAuthentication(ctx context.Context) (*discovery.OAuthFlowResu
 		}
 
 		flowConfig := &discovery.OAuthFlowConfig{
-			ClientID:     remoteAuthFlags.RemoteAuthClientID,
-			ClientSecret: clientSecret,
-			AuthorizeURL: remoteAuthFlags.RemoteAuthAuthorizeURL,
-			TokenURL:     remoteAuthFlags.RemoteAuthTokenURL,
-			Scopes:       remoteAuthFlags.RemoteAuthScopes,
-			CallbackPort: remoteAuthFlags.RemoteAuthCallbackPort,
-			Timeout:      remoteAuthFlags.RemoteAuthTimeout,
-			SkipBrowser:  remoteAuthFlags.RemoteAuthSkipBrowser,
+			ClientID:       remoteAuthFlags.RemoteAuthClientID,
+			ClientSecret:   clientSecret,
+			AuthorizeURL:   remoteAuthFlags.RemoteAuthAuthorizeURL,
+			TokenURL:       remoteAuthFlags.RemoteAuthTokenURL,
+			Scopes:         remoteAuthFlags.RemoteAuthScopes,
+			CallbackPort:   remoteAuthFlags.RemoteAuthCallbackPort,
+			Timeout:        remoteAuthFlags.RemoteAuthTimeout,
+			SkipBrowser:    remoteAuthFlags.RemoteAuthSkipBrowser,
+			ScopeParamName: remoteAuthFlags.RemoteAuthScopeParamName,
 		}
 
 		result, err := discovery.PerformOAuthFlow(ctx, remoteAuthFlags.RemoteAuthIssuer, flowConfig)
@@ -390,14 +391,15 @@ func handleOutgoingAuthentication(ctx context.Context) (*discovery.OAuthFlowResu
 
 		// Perform OAuth flow with discovered configuration
 		flowConfig := &discovery.OAuthFlowConfig{
-			ClientID:     remoteAuthFlags.RemoteAuthClientID,
-			ClientSecret: clientSecret,
-			AuthorizeURL: remoteAuthFlags.RemoteAuthAuthorizeURL,
-			TokenURL:     remoteAuthFlags.RemoteAuthTokenURL,
-			Scopes:       remoteAuthFlags.RemoteAuthScopes,
-			CallbackPort: remoteAuthFlags.RemoteAuthCallbackPort,
-			Timeout:      remoteAuthFlags.RemoteAuthTimeout,
-			SkipBrowser:  remoteAuthFlags.RemoteAuthSkipBrowser,
+			ClientID:       remoteAuthFlags.RemoteAuthClientID,
+			ClientSecret:   clientSecret,
+			AuthorizeURL:   remoteAuthFlags.RemoteAuthAuthorizeURL,
+			TokenURL:       remoteAuthFlags.RemoteAuthTokenURL,
+			Scopes:         remoteAuthFlags.RemoteAuthScopes,
+			CallbackPort:   remoteAuthFlags.RemoteAuthCallbackPort,
+			Timeout:        remoteAuthFlags.RemoteAuthTimeout,
+			SkipBrowser:    remoteAuthFlags.RemoteAuthSkipBrowser,
+			ScopeParamName: remoteAuthFlags.RemoteAuthScopeParamName,
 		}
 
 		result, err := discovery.PerformOAuthFlow(ctx, authInfo.Realm, flowConfig)

cmd/thv/app/run_flags.go

@@ -899,6 +899,9 @@ func getRemoteAuthFromRemoteServerMetadata(
 		authCfg.OAuthParams = oc.OAuthParams
 	}
 
+	// ScopeParamName: from CLI flag only (not yet supported in registry metadata)
+	authCfg.ScopeParamName = f.RemoteAuthScopeParamName
+
 	// Resolve bearer token from multiple sources (flag, file, environment variable)
 	resolvedBearerToken, err := resolveSecret(
 		f.RemoteAuthBearerToken,
@@ -960,6 +963,7 @@ func getRemoteAuthFromRunFlags(runFlags *RunFlags) (*remote.Config, error) {
 		ClientID:        runFlags.RemoteAuthFlags.RemoteAuthClientID,
 		ClientSecret:    clientSecret,
 		Scopes:          runFlags.RemoteAuthFlags.RemoteAuthScopes,
+		ScopeParamName:  runFlags.RemoteAuthFlags.RemoteAuthScopeParamName,
 		SkipBrowser:     runFlags.RemoteAuthFlags.RemoteAuthSkipBrowser,
 		Timeout:         runFlags.RemoteAuthFlags.RemoteAuthTimeout,
 		CallbackPort:    runFlags.RemoteAuthFlags.RemoteAuthCallbackPort,

pkg/auth/discovery/discovery.go

@@ -509,6 +509,7 @@ type OAuthFlowConfig struct {
 	SkipBrowser          bool
 	Resource             string // RFC 8707 resource indicator (optional)
 	OAuthParams          map[string]string
+	ScopeParamName       string // Override scope query parameter name (e.g., "user_scope" for Slack)
 }
 
 // OAuthFlowResult contains the result of an OAuth flow
@@ -645,6 +646,7 @@ func createOAuthConfig(ctx context.Context, issuer string, config *OAuthFlowConf
 			config.CallbackPort,
 			config.Resource,
 			config.OAuthParams,
+			config.ScopeParamName,
 		)
 	}
 

pkg/auth/oauth/flow.go

@@ -15,6 +15,7 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"strings"
 	"syscall"
 	"time"
 
@@ -60,6 +61,13 @@ type Config struct {
 
 	// OAuthParams are additional parameters to pass to the authorization URL
 	OAuthParams map[string]string
+
+	// ScopeParamName overrides the query parameter name used to send scopes in the
+	// authorization URL. When empty (default), the standard "scope" parameter is used.
+	// Some providers use non-standard parameter names (e.g., Slack uses "user_scope"
+	// for user-token scopes). When set, scopes are sent under this parameter name
+	// instead of "scope", and the standard "scope" parameter is cleared.
+	ScopeParamName string
 }
 
 // Flow handles the OAuth authentication flow
@@ -267,6 +275,18 @@ func (f *Flow) buildAuthURL() string {
 		}
 	}
 
+	// When a custom scope parameter name is configured, move scopes from the
+	// standard "scope" parameter to the custom one. This supports OAuth providers
+	// that use non-standard parameter names (e.g., Slack's "user_scope").
+	// The standard "scope" is cleared by setting it to empty; oauth2Config.Scopes
+	// is preserved so token refresh requests still include scopes correctly.
+	if f.config.ScopeParamName != "" && len(f.oauth2Config.Scopes) > 0 {
+		opts = append(opts,
+			oauth2.SetAuthURLParam("scope", ""),
+			oauth2.SetAuthURLParam(f.config.ScopeParamName, strings.Join(f.oauth2Config.Scopes, " ")),
+		)
+	}
+
 	// Add PKCE parameters if enabled
 	if f.config.UsePKCE {
 		opts = append(opts,

pkg/auth/oauth/flow_test.go

@@ -255,6 +255,48 @@ func TestBuildAuthURL(t *testing.T) {
 				assert.Equal(t, "S256", query.Get("code_challenge_method"))
 			},
 		},
+		{
+			name: "auth URL with custom scope parameter name",
+			config: &Config{
+				ClientID:       "test-client",
+				AuthURL:        "https://example.com/auth",
+				TokenURL:       "https://example.com/token",
+				Scopes:         []string{"search:read", "chat:write"},
+				ScopeParamName: "user_scope",
+			},
+			validate: func(t *testing.T, authURL string, flow *Flow) {
+				t.Helper()
+				parsedURL, err := url.Parse(authURL)
+				require.NoError(t, err)
+
+				query := parsedURL.Query()
+				// Standard "scope" should be cleared
+				assert.Empty(t, query.Get("scope"))
+				// Scopes should appear under the custom parameter name
+				assert.Contains(t, query.Get("user_scope"), "search:read")
+				assert.Contains(t, query.Get("user_scope"), "chat:write")
+			},
+		},
+		{
+			name: "auth URL with scope param name but no scopes",
+			config: &Config{
+				ClientID:       "test-client",
+				AuthURL:        "https://example.com/auth",
+				TokenURL:       "https://example.com/token",
+				Scopes:         []string{},
+				ScopeParamName: "user_scope",
+			},
+			validate: func(t *testing.T, authURL string, flow *Flow) {
+				t.Helper()
+				parsedURL, err := url.Parse(authURL)
+				require.NoError(t, err)
+
+				query := parsedURL.Query()
+				// Neither scope nor user_scope should be present
+				assert.Empty(t, query.Get("scope"))
+				assert.Empty(t, query.Get("user_scope"))
+			},
+		},
 	}
 
 	for _, tt := range tests {

pkg/auth/oauth/manual.go

@@ -19,6 +19,7 @@ func CreateOAuthConfigManual(
 	callbackPort int,
 	resource string,
 	oauthParams map[string]string,
+	scopeParamName string,
 ) (*Config, error) {
 	if clientID == "" {
 		return nil, fmt.Errorf("client ID is required")
@@ -44,14 +45,15 @@ func CreateOAuthConfigManual(
 	}
 
 	return &Config{
-		ClientID:     clientID,
-		ClientSecret: clientSecret,
-		AuthURL:      authURL,
-		TokenURL:     tokenURL,
-		Scopes:       scopes,
-		UsePKCE:      usePKCE,
-		CallbackPort: callbackPort,
-		Resource:     resource,
-		OAuthParams:  oauthParams,
+		ClientID:       clientID,
+		ClientSecret:   clientSecret,
+		AuthURL:        authURL,
+		TokenURL:       tokenURL,
+		Scopes:         scopes,
+		UsePKCE:        usePKCE,
+		CallbackPort:   callbackPort,
+		Resource:       resource,
+		OAuthParams:    oauthParams,
+		ScopeParamName: scopeParamName,
 	}, nil
 }

pkg/auth/oauth/manual_test.go

@@ -269,6 +269,7 @@ func TestCreateOAuthConfigManual(t *testing.T) {
 				tt.callbackPort,
 				tt.resource,
 				oauthParams,
+				"",
 			)
 
 			if tt.expectError {
@@ -335,6 +336,7 @@ func TestCreateOAuthConfigManual_ScopeDefaultBehavior(t *testing.T) {
 				8080,
 				"",
 				nil, // No OAuth params for basic tests
+				"",  // No scope param name override
 			)
 
 			require.NoError(t, err)
@@ -378,6 +380,7 @@ func TestCreateOAuthConfigManual_PKCEBehavior(t *testing.T) {
 				8080,
 				"",
 				nil, // No OAuth params for basic tests
+				"",  // No scope param name override
 			)
 
 			require.NoError(t, err)
@@ -426,6 +429,7 @@ func TestCreateOAuthConfigManual_CallbackPortBehavior(t *testing.T) {
 				tt.port,
 				"",
 				nil, // No OAuth params for basic tests
+				"",  // No scope param name override
 			)
 
 			require.NoError(t, err)
@@ -491,6 +495,7 @@ func TestCreateOAuthConfigManual_OAuthParamsBehavior(t *testing.T) {
 				8080,
 				"",
 				tt.oauthParams,
+				"",
 			)
 
 			require.NoError(t, err)

pkg/auth/remote/config.go

@@ -44,6 +44,11 @@ type Config struct {
 	// OAuth parameters for server-specific customization
 	OAuthParams map[string]string `json:"oauth_params,omitempty" yaml:"oauth_params,omitempty"`
 
+	// ScopeParamName overrides the query parameter name used to send scopes in the
+	// authorization URL. When empty, the standard "scope" parameter is used.
+	// Some providers require a non-standard name (e.g., Slack uses "user_scope").
+	ScopeParamName string `json:"scope_param_name,omitempty" yaml:"scope_param_name,omitempty"`
+
 	// Bearer token configuration (alternative to OAuth)
 	BearerToken     string `json:"bearer_token,omitempty" yaml:"bearer_token,omitempty"` //nolint:gosec // G117
 	BearerTokenFile string `json:"bearer_token_file,omitempty" yaml:"bearer_token_file,omitempty"`

pkg/auth/remote/handler.go

@@ -155,7 +155,8 @@ func (h *Handler) buildOAuthFlowConfig(scopes []string, authServerInfo *discover
 		Timeout:      h.config.Timeout,
 		SkipBrowser:  h.config.SkipBrowser,
 		Resource:     h.config.Resource,
-		OAuthParams:  h.config.OAuthParams,
+		OAuthParams:    h.config.OAuthParams,
+		ScopeParamName: h.config.ScopeParamName,
 	}
 
 	// If we have discovered endpoints from the authorization server metadata,