modelcontextprotocol/csharp-sdk
Watch
1
0
Fork
You've already forked csharp-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Implement RFC 9207 issuer validation in ClientOAuthProvider (#1605)

Browse source
This commit is contained in:
Mike Kistler 2026-07-23 08:01:22 -07:00 • committed by GitHub
commit 4aade88558
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 707 additions and 149 deletions
Download patch file Download diff file Expand all files Collapse all files

17
src/ModelContextProtocol.Core/Authentication/AuthorizationCallbackContext.cs Normal file
View file

@ -0,0 +1,17 @@
namespace ModelContextProtocol.Authentication;
/// <summary>
/// Provides the information needed to complete an OAuth authorization request.
/// </summary>
public sealed class AuthorizationCallbackContext
{
/// <summary>
/// Gets the authorization URI that the user needs to visit.
/// </summary>
public required Uri AuthorizationUri { get; init; }
/// <summary>
/// Gets the redirect URI where the authorization response will be sent.
/// </summary>
public required Uri RedirectUri { get; init; }
}

26
src/ModelContextProtocol.Core/Authentication/AuthorizationRedirectDelegate.cs
View file

@ -1,4 +1,3 @@

namespace ModelContextProtocol.Authentication;
/// <summary>
@ -9,20 +8,13 @@ namespace ModelContextProtocol.Authentication;
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
/// <returns>A task that represents the asynchronous operation. The task result contains the authorization code if successful, or null if the operation failed or was cancelled.</returns>
/// <remarks>
/// <para>
/// This delegate provides SDK consumers with full control over how the OAuth authorization flow is handled.
/// Implementers can choose to:
/// </para>
/// <list type="bullet">
/// <item><description>Start a local HTTP server and open a browser (default behavior)</description></item>
/// <item><description>Display the authorization URL to the user for manual handling</description></item>
/// <item><description>Integrate with a custom UI or authentication flow</description></item>
/// <item><description>Use a different redirect mechanism altogether</description></item>
/// </list>
/// <para>
/// The implementation should handle user interaction to visit the authorization URL and extract
/// the authorization code from the callback. The authorization code is typically provided as
/// a query parameter in the redirect URI callback.
/// </para>
/// This delegate cannot return the <c>iss</c> parameter from the authorization response, so
/// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see> issuer validation is
/// skipped when it is used. Use <see cref="ClientOAuthOptions.AuthorizationCallbackHandler"/> for
/// issuer-aware authorization flows.
/// </remarks>
public delegate Task<string?> AuthorizationRedirectDelegate(Uri authorizationUri, Uri redirectUri, CancellationToken cancellationToken);
[Obsolete(
ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_Message,
DiagnosticId = ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_DiagnosticId,
UrlFormat = ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_Url)]
public delegate Task<string?> AuthorizationRedirectDelegate(Uri authorizationUri, Uri redirectUri, CancellationToken cancellationToken);

39
src/ModelContextProtocol.Core/Authentication/AuthorizationResult.cs Normal file
View file

@ -0,0 +1,39 @@
namespace ModelContextProtocol.Authentication;
/// <summary>
/// Represents the result of an OAuth authorization redirect, containing the authorization code
/// and optionally the issuer identifier from the authorization response.
/// </summary>
/// <remarks>
/// <para>
/// The <see cref="Iss"/> property should be populated from the <c>iss</c> query parameter in the
/// redirect URI when present, as specified by
/// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
/// This enables the SDK to validate that the authorization response originated from the expected
/// authorization server, mitigating mix-up attacks.
/// </para>
/// </remarks>
public sealed class AuthorizationResult
{
/// <summary>
/// Gets the authorization code returned by the authorization server.
/// </summary>
public string? Code { get; init; }
/// <summary>
/// Gets the issuer identifier returned in the authorization response per
/// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
/// </summary>
/// <remarks>
/// <para>
/// This value should be extracted from the <c>iss</c> query parameter of the redirect URI.
/// When present, the SDK validates it against the expected authorization server issuer to
/// prevent mix-up attacks.
/// </para>
/// <para>
/// Implementations of <see cref="ClientOAuthOptions.AuthorizationCallbackHandler"/> should populate this
/// property whenever the <c>iss</c> parameter is present in the redirect URI callback.
/// </para>
/// </remarks>
public string? Iss { get; init; }
}

7
src/ModelContextProtocol.Core/Authentication/AuthorizationServerMetadata.cs
View file

@ -72,4 +72,11 @@ internal sealed class AuthorizationServerMetadata
/// </summary>
[JsonPropertyName("client_id_metadata_document_supported")]
public bool ClientIdMetadataDocumentSupported { get; set; }
/// <summary>
/// Indicates whether the authorization server includes the <c>iss</c> parameter in authorization responses
/// as defined in <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
/// </summary>
[JsonPropertyName("authorization_response_iss_parameter_supported")]
public bool AuthorizationResponseIssParameterSupported { get; set; }
}

34
src/ModelContextProtocol.Core/Authentication/ClientOAuthOptions.cs
View file

@ -70,18 +70,44 @@ public sealed class ClientOAuthOptions
public ScopeSelectorDelegate? ScopeSelector { get; set; }
/// <summary>
/// Gets or sets the authorization redirect delegate for handling the OAuth authorization flow.
/// Gets or sets the callback that handles the OAuth authorization flow.
/// </summary>
/// <remarks>
/// <para>
/// This delegate is responsible for handling the OAuth authorization URL and obtaining the authorization code.
/// If not specified, a default implementation will be used that prompts the user to enter the code manually.
/// This callback receives the authorization and redirect URIs in an
/// <see cref="AuthorizationCallbackContext"/> and returns the authorization response.
/// If not specified, a default implementation prompts the user to enter the full redirect URL manually.
/// </para>
/// <para>
/// Custom implementations might open a browser, start an HTTP listener, or use other mechanisms to capture
/// the authorization code from the OAuth redirect.
/// the authorization response. They should return both the <c>code</c> and <c>iss</c> query parameters
/// from the redirect URI callback. This enables the SDK to validate the <c>iss</c> parameter per
/// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>, which mitigates
/// mix-up attacks.
/// </para>
/// <para>
/// This property cannot be configured together with <see cref="AuthorizationRedirectDelegate"/>.
/// </para>
/// </remarks>
public Func<AuthorizationCallbackContext, CancellationToken, Task<AuthorizationResult?>>? AuthorizationCallbackHandler { get; set; }
/// <summary>
/// Gets or sets the legacy authorization redirect delegate for handling the OAuth authorization flow.
/// </summary>
/// <remarks>
/// <para>
/// This delegate returns only the authorization code and cannot provide the <c>iss</c> parameter from
/// the authorization response. Consequently, RFC 9207 issuer validation is skipped when this delegate
/// is used. Use <see cref="AuthorizationCallbackHandler"/> for issuer-aware authorization flows.
/// </para>
/// <para>
/// This property cannot be configured together with <see cref="AuthorizationCallbackHandler"/>.
/// </para>
/// </remarks>
[Obsolete(
ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_Message,
DiagnosticId = ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_DiagnosticId,
UrlFormat = ModelContextProtocol.Obsoletions.AuthorizationRedirectDelegate_Url)]
public AuthorizationRedirectDelegate? AuthorizationRedirectDelegate { get; set; }
/// <summary>

172
src/ModelContextProtocol.Core/Authentication/ClientOAuthProvider.cs
View file

@ -31,7 +31,8 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
private readonly ScopeSelectorDelegate? _scopeSelector;
private readonly IDictionary<string, string> _additionalAuthorizationParameters;
private readonly Func<IReadOnlyList<Uri>, Uri?> _authServerSelector;
private readonly AuthorizationRedirectDelegate _authorizationRedirectDelegate;
private readonly Func<AuthorizationCallbackContext, CancellationToken, Task<AuthorizationResult?>> _authorizationCallbackHandler;
private readonly bool _validateAuthorizationResponseIssuer;
private readonly Uri? _clientMetadataDocumentUri;
// _dcrClientName, _dcrClientUri, _dcrInitialAccessToken, _dcrConfiguredApplicationType and _dcrResponseDelegate are used for dynamic client registration (RFC 7591)
@ -104,8 +105,39 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
// Set up authorization server selection strategy
_authServerSelector = options.AuthServerSelector ?? DefaultAuthServerSelector;
// Set up authorization URL handler (use default if not provided)
_authorizationRedirectDelegate = options.AuthorizationRedirectDelegate ?? DefaultAuthorizationUrlHandler;
// Set up authorization callback handler (use default if not provided).
#pragma warning disable MCP9007 // Read the obsolete property to provide source and binary compatibility.
var authorizationRedirectDelegate = options.AuthorizationRedirectDelegate;
if (options.AuthorizationCallbackHandler is not null && authorizationRedirectDelegate is not null)
{
throw new ArgumentException(
$"{nameof(ClientOAuthOptions.AuthorizationCallbackHandler)} and {nameof(ClientOAuthOptions.AuthorizationRedirectDelegate)} cannot both be configured.",
nameof(options));
}
#pragma warning restore MCP9007
if (options.AuthorizationCallbackHandler is not null)
{
_authorizationCallbackHandler = options.AuthorizationCallbackHandler;
_validateAuthorizationResponseIssuer = true;
}
else if (authorizationRedirectDelegate is not null)
{
_authorizationCallbackHandler = async (context, cancellationToken) => new AuthorizationResult
{
Code = await authorizationRedirectDelegate(
context.AuthorizationUri,
context.RedirectUri,
cancellationToken).ConfigureAwait(false),
};
_validateAuthorizationResponseIssuer = false;
}
else
{
_authorizationCallbackHandler = DefaultAuthorizationUrlHandler;
_validateAuthorizationResponseIssuer = true;
}
_dcrClientName = options.DynamicClientRegistration?.ClientName;
_dcrClientUri = options.DynamicClientRegistration?.ClientUri;
@ -125,18 +157,30 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
/// <summary>
/// Default authorization URL handler that displays the URL to the user for manual input.
/// </summary>
/// <param name="authorizationUrl">The authorization URL to handle.</param>
/// <param name="redirectUri">The redirect URI where the authorization code will be sent.</param>
/// <param name="context">The context containing the authorization and redirect URIs.</param>
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
/// <returns>The authorization code entered by the user, or null if none was provided.</returns>
private static Task<string?> DefaultAuthorizationUrlHandler(Uri authorizationUrl, Uri redirectUri, CancellationToken cancellationToken)
/// <returns>The authorization result entered by the user, or null if none was provided.</returns>
private static Task<AuthorizationResult?> DefaultAuthorizationUrlHandler(
AuthorizationCallbackContext context,
CancellationToken cancellationToken)
{
Console.WriteLine($"Please open the following URL in your browser to authorize the application:");
Console.WriteLine($"{authorizationUrl}");
Console.WriteLine($"{context.AuthorizationUri}");
Console.WriteLine();
Console.Write("Enter the authorization code from the redirect URL: ");
var authorizationCode = Console.ReadLine();
return Task.FromResult<string?>(authorizationCode);
Console.Write("Enter the full redirect URL: ");
var redirectUrl = Console.ReadLine();
if (!Uri.TryCreate(redirectUrl, UriKind.Absolute, out var responseUri))
{
ThrowFailedToHandleUnauthorizedResponse(
"The entered redirect URL is not a valid absolute URL. Paste the full redirect URL from the browser address bar.");
}
var queryParams = HttpUtility.ParseQueryString(responseUri.Query);
return Task.FromResult<AuthorizationResult?>(new()
{
Code = queryParams["code"],
Iss = queryParams["iss"],
});
}
internal override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, JsonRpcMessage? message, CancellationToken cancellationToken)
@ -468,10 +512,41 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
ThrowFailedToHandleUnauthorizedResponse($"AuthorizationEndpoint must use HTTP or HTTPS. '{metadata.AuthorizationEndpoint}' does not meet this requirement.");
}
// Validate the issuer in the metadata document per RFC 8414 Section 3.3:
// the issuer value MUST be identical to the issuer identifier used to construct
// the well-known URL.
// Skip validation in legacy backcompat mode (resourceUri is null) because the
// authServerUri was derived from the server origin rather than from Protected
// Resource Metadata, so it may not match the server's canonical issuer.
// Note: resourceUri is null exclusively in the 2025-03-26 legacy path. For newer
// protocol versions, ExtractProtectedResourceMetadata throws if the PRM document
// omits the resource field (VerifyResourceMatch returns false for null Resource),
// so we never reach this point with resourceUri == null in non-legacy flows.
if (resourceUri is not null && metadata.Issuer is null)
{
ThrowFailedToHandleUnauthorizedResponse(
$"Authorization server metadata from '{wellKnownEndpoint}' did not provide the required issuer (RFC 8414 Section 2).");
}
// RFC 8414 requires an identical issuer value, so do not normalize URI case,
// trailing slashes, or percent-encoding before comparison.
if (resourceUri is not null &&
!string.Equals(metadata.Issuer!.OriginalString, authServerUri.OriginalString, StringComparison.Ordinal))
{
ThrowFailedToHandleUnauthorizedResponse(
$"Authorization server metadata issuer '{metadata.Issuer}' does not match the expected issuer '{authServerUri}' (RFC 8414 Section 3.3).");
}
// A structurally valid metadata document was discovered. Even if it fails PKCE validation
// below, its existence disqualifies the legacy fallback that would otherwise synthesize S256.
metadataDocumentFound = true;
}
catch (McpException)
{
// Metadata validation failures are security signals and must not fall back to
// another well-known endpoint.
throw;
}
catch (Exception ex)
{
LogErrorFetchingAuthServerMetadata(ex, wellKnownEndpoint);
@ -605,14 +680,31 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
var codeChallenge = GenerateCodeChallenge(codeVerifier);
var authUrl = BuildAuthorizationUrl(protectedResourceMetadata, authServerMetadata, codeChallenge);
var authCode = await _authorizationRedirectDelegate(authUrl, _redirectUri, cancellationToken).ConfigureAwait(false);
if (string.IsNullOrEmpty(authCode))
var authResult = await _authorizationCallbackHandler(
new AuthorizationCallbackContext
{
AuthorizationUri = authUrl,
RedirectUri = _redirectUri,
},
cancellationToken).ConfigureAwait(false);
if (authResult is null || string.IsNullOrEmpty(authResult.Code))
{
ThrowFailedToHandleUnauthorizedResponse($"The {nameof(AuthorizationRedirectDelegate)} returned a null or empty authorization code.");
ThrowFailedToHandleUnauthorizedResponse($"The {nameof(ClientOAuthOptions.AuthorizationCallbackHandler)} returned a null or empty authorization code.");
}
return await ExchangeCodeForTokenAsync(protectedResourceMetadata, authServerMetadata, authCode!, codeVerifier, cancellationToken).ConfigureAwait(false);
if (_validateAuthorizationResponseIssuer)
{
ValidateIssuerResponse(authResult!.Iss, authServerMetadata);
}
return await ExchangeCodeForTokenAsync(
protectedResourceMetadata,
authServerMetadata,
authResult.Code!,
codeVerifier,
cancellationToken).ConfigureAwait(false);
}
private Uri BuildAuthorizationUrl(
@ -999,6 +1091,56 @@ internal sealed partial class ClientOAuthProvider : McpHttpClient
return scope + " " + OfflineAccess;
}
/// <summary>
/// Validates the <c>iss</c> parameter from an authorization response per
/// <see href="https://datatracker.ietf.org/doc/html/rfc9207">RFC 9207</see>.
/// </summary>
/// <param name="iss">The issuer identifier received in the authorization response, or null if absent.</param>
/// <param name="authServerMetadata">The authorization server metadata containing the expected issuer.</param>
private void ValidateIssuerResponse(string? iss, AuthorizationServerMetadata authServerMetadata)
{
var expectedIssuer = authServerMetadata.Issuer?.OriginalString;
if ((authServerMetadata.AuthorizationResponseIssParameterSupported || !string.IsNullOrEmpty(iss)) &&
expectedIssuer is null)
{
ThrowFailedToHandleUnauthorizedResponse(
"Authorization server metadata did not provide an issuer required to validate the authorization response.");
}
if (authServerMetadata.AuthorizationResponseIssParameterSupported)
{
// Server advertises iss support: iss MUST be present and match.
if (string.IsNullOrEmpty(iss))
{
ThrowFailedToHandleUnauthorizedResponse(
"Authorization server advertises RFC 9207 iss parameter support but none was received in the authorization response.");
}
// Use exact string comparison per RFC 9207 / RFC 3986 §6.2.1.
if (!string.Equals(iss, expectedIssuer, StringComparison.Ordinal))
{
ThrowFailedToHandleUnauthorizedResponse(
$"Authorization response issuer '{iss}' does not match expected issuer '{expectedIssuer}'.");
}
}
else
{
// Server does not advertise iss support: if iss is present, still validate it.
// RFC 9207 cannot protect against a server that neither advertises support nor
// returns an iss parameter, so an absent iss is accepted in that case.
if (!string.IsNullOrEmpty(iss))
{
if (!string.Equals(iss, expectedIssuer, StringComparison.Ordinal))
{
ThrowFailedToHandleUnauthorizedResponse(
$"Authorization response issuer '{iss}' does not match expected issuer '{expectedIssuer}'.");
}
}
// If iss is absent and not advertised, proceed normally.
}
}
/// <summary>
/// Verifies that the resource URI in the metadata matches the original request URL.
/// Accepts either an exact match with the full request URL, or a match with the base URL