Complete token endpoint auth method support

Validate configured methods, preserve configured intent across authorization server migration, honor DCR negotiation, and persist the effective method for refreshes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: halter73

src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs

@@ -25,14 +25,16 @@ public sealed class ClientOAuthOptions
 
     /// <summary>
     /// Gets or sets the token endpoint authentication method (<c>token_endpoint_auth_method</c>) to use when
-    /// requesting tokens, for example <c>"none"</c>, <c>"client_secret_basic"</c>, or <c>"client_secret_post"</c>.
+    /// requesting tokens.
     /// </summary>
     /// <remarks>
-    /// When not set, the method is inferred from the dynamic client registration response (when DCR is used), and
-    /// otherwise from the first entry in the authorization server's <c>token_endpoint_auth_methods_supported</c>.
-    /// Set this explicitly when that inference is incorrect — most notably for a public client identified by a
-    /// <see cref="ClientMetadataDocumentUri">Client ID Metadata Document</see>, which must authenticate with
-    /// <c>"none"</c> (relying on PKCE) even when the authorization server advertises a different method first.
+    /// Supported values are <c>none</c>, <c>client_secret_basic</c>, and <c>client_secret_post</c>.
+    /// When not set, the method is inferred from the dynamic client registration response (when DCR is used),
+    /// and otherwise from the first entry in the authorization server's
+    /// <c>token_endpoint_auth_methods_supported</c>. For DCR, this value is requested during registration,
+    /// but the method returned by the authorization server is authoritative.
+    /// Set this explicitly when inference is incorrect, most notably for a public client identified by a
+    /// <see cref="ClientMetadataDocumentUri">Client ID Metadata Document</see>, which commonly uses <c>none</c>.
     /// </remarks>
     public string? TokenEndpointAuthMethod { get; set; }
 

src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs

@@ -36,6 +36,7 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
     private readonly bool _validateAuthorizationResponseIssuer;
     private readonly Uri? _clientMetadataDocumentUri;
     private readonly string? _configuredClientId;
+    private readonly string? _configuredTokenEndpointAuthMethod;
 
     // _dcrClientName, _dcrClientUri, _dcrInitialAccessToken, _dcrConfiguredApplicationType and _dcrResponseDelegate are used for dynamic client registration (RFC 7591)
     private readonly string? _dcrClientName;
@@ -97,10 +98,19 @@ public ClientOAuthProvider(
             throw new ArgumentNullException(nameof(options));
         }
 
+        if (options.TokenEndpointAuthMethod is not null &&
+            !IsSupportedTokenEndpointAuthMethod(options.TokenEndpointAuthMethod))
+        {
+            throw new ArgumentException(
+                $"{nameof(options.TokenEndpointAuthMethod)} must be 'client_secret_basic', 'client_secret_post', or 'none'.",
+                $"{nameof(options)}.{nameof(options.TokenEndpointAuthMethod)}");
+        }
+
         _clientId = options.ClientId;
         _configuredClientId = options.ClientId;
         _clientSecret = options.ClientSecret;
-        _tokenEndpointAuthMethod = options.TokenEndpointAuthMethod;
+        _configuredTokenEndpointAuthMethod = options.TokenEndpointAuthMethod;
+        _tokenEndpointAuthMethod = _configuredTokenEndpointAuthMethod;
         _redirectUri = options.RedirectUri ?? throw new ArgumentException("ClientOAuthOptions.RedirectUri must configured.", nameof(options));
         _configuredScopes = options.Scopes is null ? null : string.Join(" ", options.Scopes);
         _scopeSelector = options.ScopeSelector;
@@ -848,12 +858,17 @@ private HttpRequestMessage CreateTokenRequest(Uri tokenEndpoint, Dictionary<stri
             // Public client: include client_id in the body but no secret.
             formFields["client_id"] = clientId;
         }
-        else
+        else if (_tokenEndpointAuthMethod is null or "client_secret_post")
         {
             // Default to client_secret_post: include credentials in the body.
             formFields["client_id"] = clientId;
             formFields["client_secret"] = _clientSecret ?? string.Empty;
         }
+        else
+        {
+            ThrowFailedToHandleUnauthorizedResponse(
+                $"Token endpoint authentication method '{_tokenEndpointAuthMethod}' is not supported.");
+        }
 
         request.Content = new FormUrlEncodedContent(formFields);
         return request;
@@ -935,7 +950,7 @@ private async Task PerformDynamicClientRegistrationAsync(
             RedirectUris = [_redirectUri.ToString()],
             GrantTypes = ["authorization_code", "refresh_token"],
             ResponseTypes = ["code"],
-            TokenEndpointAuthMethod = "client_secret_post",
+            TokenEndpointAuthMethod = _configuredTokenEndpointAuthMethod ?? "client_secret_post",
             ClientName = _dcrClientName,
             ClientUri = _dcrClientUri?.ToString(),
             Scope = ComputeEffectiveScope(protectedResourceMetadata, authServerMetadata),
@@ -984,11 +999,23 @@ private async Task PerformDynamicClientRegistrationAsync(
             _clientSecret = registrationResponse.ClientSecret;
         }
 
-        // Honor an explicitly configured ClientOAuthOptions.TokenEndpointAuthMethod over the value returned by
-        // dynamic client registration.
-        if (!string.IsNullOrEmpty(registrationResponse.TokenEndpointAuthMethod))
+        // The response describes the registration the server created and is authoritative. Some servers omit the
+        // field, in which case use the method requested during registration.
+        var registeredTokenEndpointAuthMethod = registrationResponse.TokenEndpointAuthMethod;
+        if (!string.IsNullOrEmpty(registeredTokenEndpointAuthMethod))
+        {
+            if (!IsSupportedTokenEndpointAuthMethod(registeredTokenEndpointAuthMethod!))
+            {
+                ThrowFailedToHandleUnauthorizedResponse(
+                    $"Dynamic client registration returned unsupported token endpoint authentication method " +
+                    $"'{registeredTokenEndpointAuthMethod}'.");
+            }
+
+            _tokenEndpointAuthMethod = registeredTokenEndpointAuthMethod;
+        }
+        else
         {
-            _tokenEndpointAuthMethod ??= registrationResponse.TokenEndpointAuthMethod;
+            _tokenEndpointAuthMethod = registrationRequest.TokenEndpointAuthMethod;
         }
 
         LogDynamicClientRegistrationSuccessful(_clientId!);
@@ -1011,6 +1038,9 @@ private static string InferApplicationType(Uri redirectUri)
         return "native";
     }
 
+    private static bool IsSupportedTokenEndpointAuthMethod(string tokenEndpointAuthMethod) =>
+        tokenEndpointAuthMethod is "client_secret_basic" or "client_secret_post" or "none";
+
     private static string? GetResourceUri(ProtectedResourceMetadata protectedResourceMetadata)
         => protectedResourceMetadata.Resource;
 
@@ -1528,7 +1558,16 @@ private void RestoreCachedClientCredentials(TokenContainer? tokens, Uri selected
         // Assign _clientId last. Callers treat a non-empty _clientId as "registration complete", so the
         // secret and auth method must already be in place before _clientId becomes observable.
         _clientSecret ??= cached.ClientSecret;
-        _tokenEndpointAuthMethod ??= cached.TokenEndpointAuthMethod;
+        if (string.Equals(cached.ClientId, _clientMetadataDocumentUri?.AbsoluteUri, StringComparison.Ordinal))
+        {
+            // Configured intent controls CIMD clients.
+            _tokenEndpointAuthMethod ??= cached.TokenEndpointAuthMethod;
+        }
+        else
+        {
+            // A DCR response is authoritative for the registration and must survive a cold start.
+            _tokenEndpointAuthMethod = cached.TokenEndpointAuthMethod ?? _configuredTokenEndpointAuthMethod;
+        }
         _clientId = cached.ClientId;
         _clientCredentialsAuthorizationServer = cached.AuthorizationServer;
     }
@@ -1557,7 +1596,7 @@ private void BindClientCredentialsToAuthorizationServer(Uri selectedAuthServer)
 
         _clientId = null;
         _clientSecret = null;
-        _tokenEndpointAuthMethod = null;
+        _tokenEndpointAuthMethod = _configuredTokenEndpointAuthMethod;
         _authServerMetadata = null;
         _clientCredentialsAuthorizationServer = null;
     }

tests/ModelContextProtocol.AspNetCore.Tests/OAuth/AuthTests.cs

@@ -50,6 +50,32 @@ public async Task CanAuthenticate()
             transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
     }
 
+    [Theory]
+    [InlineData("client_secret_basic")]
+    [InlineData("client_secret_post")]
+    public async Task CanAuthenticate_WithExplicitTokenEndpointAuthMethod(string tokenEndpointAuthMethod)
+    {
+        await using var app = await StartMcpServerAsync();
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new(McpServerUrl),
+            OAuth = new()
+            {
+                ClientId = "demo-client",
+                ClientSecret = "demo-secret",
+                TokenEndpointAuthMethod = tokenEndpointAuthMethod,
+                RedirectUri = new Uri("http://localhost:1179/callback"),
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
+            },
+        }, HttpClient, LoggerFactory);
+
+        await using var client = await McpClient.CreateAsync(
+            transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal(tokenEndpointAuthMethod, TestOAuthServer.LastTokenEndpointAuthMethod);
+    }
+
     [Fact]
     public async Task AuthorizationCallbackHandler_ReceivesConfiguredRedirectUri()
     {
@@ -176,6 +202,28 @@ public void HttpClientTransport_RejectsBothAuthorizationCallbacks()
 #pragma warning restore MCP9007
     }
 
+    [Theory]
+    [InlineData("")]
+    [InlineData("None")]
+    [InlineData("private_key_jwt")]
+    public void HttpClientTransport_RejectsUnsupportedTokenEndpointAuthMethod(string tokenEndpointAuthMethod)
+    {
+        var ex = Assert.Throws<ArgumentException>(() => new HttpClientTransport(
+            new()
+            {
+                Endpoint = new(McpServerUrl),
+                OAuth = new()
+                {
+                    RedirectUri = new Uri("http://localhost:1179/callback"),
+                    TokenEndpointAuthMethod = tokenEndpointAuthMethod,
+                },
+            },
+            HttpClient,
+            LoggerFactory));
+
+        Assert.Equal("options.TokenEndpointAuthMethod", ex.ParamName);
+    }
+
     [Fact]
     public async Task CanAuthenticate_WhenAuthorizationResponseStateMatches()
     {
@@ -309,6 +357,80 @@ public async Task CanAuthenticate_WithDynamicClientRegistration()
             transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
 
         Assert.Equal("native", TestOAuthServer.LastApplicationType);
+        Assert.Equal("client_secret_post", TestOAuthServer.LastRegistrationTokenEndpointAuthMethod);
+    }
+
+    [Fact]
+    public async Task DynamicClientRegistration_ResponseTokenEndpointAuthMethodIsAuthoritative()
+    {
+        TestOAuthServer.DynamicRegistrationTokenEndpointAuthMethod = "client_secret_post";
+        await using var app = await StartMcpServerAsync();
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new(McpServerUrl),
+            OAuth = new()
+            {
+                RedirectUri = new Uri("http://localhost:1179/callback"),
+                TokenEndpointAuthMethod = "client_secret_basic",
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
+                DynamicClientRegistration = new(),
+            },
+        }, HttpClient, LoggerFactory);
+
+        await using var client = await McpClient.CreateAsync(
+            transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("client_secret_basic", TestOAuthServer.LastRegistrationTokenEndpointAuthMethod);
+        Assert.Equal("client_secret_post", TestOAuthServer.LastTokenEndpointAuthMethod);
+    }
+
+    [Fact]
+    public async Task DynamicClientRegistration_UsesRequestedMethodWhenResponseOmitsIt()
+    {
+        TestOAuthServer.DynamicRegistrationTokenEndpointAuthMethod = null;
+        await using var app = await StartMcpServerAsync();
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new(McpServerUrl),
+            OAuth = new()
+            {
+                RedirectUri = new Uri("http://localhost:1179/callback"),
+                TokenEndpointAuthMethod = "client_secret_basic",
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
+                DynamicClientRegistration = new(),
+            },
+        }, HttpClient, LoggerFactory);
+
+        await using var client = await McpClient.CreateAsync(
+            transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("client_secret_basic", TestOAuthServer.LastRegistrationTokenEndpointAuthMethod);
+        Assert.Equal("client_secret_basic", TestOAuthServer.LastTokenEndpointAuthMethod);
+    }
+
+    [Fact]
+    public async Task DynamicClientRegistration_RejectsUnsupportedResponseTokenEndpointAuthMethod()
+    {
+        TestOAuthServer.DynamicRegistrationTokenEndpointAuthMethod = "private_key_jwt";
+        await using var app = await StartMcpServerAsync();
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new(McpServerUrl),
+            OAuth = new()
+            {
+                RedirectUri = new Uri("http://localhost:1179/callback"),
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
+                DynamicClientRegistration = new(),
+            },
+        }, HttpClient, LoggerFactory);
+
+        var ex = await Assert.ThrowsAsync<McpException>(() => McpClient.CreateAsync(
+            transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken));
+
+        Assert.Contains("private_key_jwt", ex.Message);
     }
 
     [Fact]
@@ -457,7 +579,7 @@ public async Task CannotAuthenticate_WithClientMetadataDocument_WhenServerAdvert
             OAuth = new ClientOAuthOptions()
             {
                 RedirectUri = new Uri("http://localhost:1179/callback"),
-                AuthorizationRedirectDelegate = HandleAuthorizationUrlAsync,
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
                 ClientMetadataDocumentUri = new Uri(ClientMetadataDocumentUrl),
             },
         }, HttpClient, LoggerFactory);
@@ -482,7 +604,7 @@ public async Task CanAuthenticate_WithClientMetadataDocument_AndExplicitNoneAuth
             OAuth = new ClientOAuthOptions()
             {
                 RedirectUri = new Uri("http://localhost:1179/callback"),
-                AuthorizationRedirectDelegate = HandleAuthorizationUrlAsync,
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
                 ClientMetadataDocumentUri = new Uri(ClientMetadataDocumentUrl),
                 TokenEndpointAuthMethod = "none",
             },
@@ -492,6 +614,77 @@ public async Task CanAuthenticate_WithClientMetadataDocument_AndExplicitNoneAuth
             transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
     }
 
+    [Fact]
+    public async Task ClientMetadataDocument_PreservesConfiguredMethodAfterAuthorizationServerMigration()
+    {
+        TestOAuthServer.SupportedTokenEndpointAuthMethods = ["client_secret_basic", "none"];
+        var selectedAuthorizationServer = OAuthServerUrl;
+        var migrationChallengeSent = 0;
+
+        Builder.Services.Configure<McpAuthenticationOptions>(McpAuthenticationDefaults.AuthenticationScheme, options =>
+        {
+            options.Events.OnResourceMetadataRequest = async context =>
+            {
+                context.HandleResponse();
+                var metadata = new ProtectedResourceMetadata
+                {
+                    Resource = McpServerUrl,
+                    AuthorizationServers = { selectedAuthorizationServer },
+                    ScopesSupported = ["mcp:tools"],
+                };
+                await Results.Json(metadata, McpJsonUtilities.DefaultOptions).ExecuteAsync(context.HttpContext);
+            };
+        });
+
+        await using var app = await StartMcpServerAsync(configureMiddleware: app =>
+        {
+            app.Use(async (context, next) =>
+            {
+                if (context.Request.Method == HttpMethods.Post && context.Request.Path == "/")
+                {
+                    context.Request.EnableBuffering();
+                    var message = await JsonSerializer.DeserializeAsync(
+                        context.Request.Body,
+                        McpJsonUtilities.DefaultOptions.GetTypeInfo(typeof(JsonRpcMessage)),
+                        context.RequestAborted) as JsonRpcMessage;
+                    context.Request.Body.Position = 0;
+
+                    if (message is JsonRpcRequest { Method: "ping" } &&
+                        Interlocked.CompareExchange(ref migrationChallengeSent, 1, 0) == 0)
+                    {
+                        selectedAuthorizationServer = $"{OAuthServerUrl}/tenant";
+                        context.Response.StatusCode = StatusCodes.Status401Unauthorized;
+                        context.Response.Headers.WWWAuthenticate =
+                            $"{JwtBearerDefaults.AuthenticationScheme} resource_metadata=\"{McpServerUrl}/.well-known/oauth-protected-resource\"";
+                        return;
+                    }
+                }
+
+                await next(context);
+            });
+        });
+
+        await using var transport = new HttpClientTransport(new()
+        {
+            Endpoint = new(McpServerUrl),
+            OAuth = new()
+            {
+                RedirectUri = new Uri("http://localhost:1179/callback"),
+                AuthorizationCallbackHandler = HandleAuthorizationUrlAsync,
+                ClientMetadataDocumentUri = new Uri(ClientMetadataDocumentUrl),
+                TokenEndpointAuthMethod = "none",
+            },
+        }, HttpClient, LoggerFactory);
+
+        await using var client = await McpClient.CreateAsync(
+            transport, loggerFactory: LoggerFactory, cancellationToken: TestContext.Current.CancellationToken);
+
+        await client.PingAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        Assert.Equal("none", TestOAuthServer.LastTokenEndpointAuthMethod);
+        Assert.Contains("/.well-known/oauth-authorization-server/tenant", TestOAuthServer.MetadataRequests);
+    }
+
     [Fact]
     public async Task UsesDynamicClientRegistration_WhenCimdNotSupported()
     {