Authorization Server & Protected Resource Metadata inspection

ClientOAuthOptions と、認可サーバーおよび保護されたリソースのメタデータを取得する MCP クライアントパスから始めます。既存の AuthorizationRedirectDelegate と関連する認証コードを確認し、その後、提案されている delegate および ClientOAuthEvents の設計を、キャッシュに関する問題も含めて比較します。完了の条件は、選択した公開 API が要求されたメタデータへのアクセスを一貫して公開し、選択したコールバックのカバレッジがあることです。

Sometimes we need access to the AS metadata & PRM. For example, if we want to implement logout we need access to the logout endpoint which resides on the AS metadata, and this AS metadata is already fetched by the MCP client. Another use case is to conditionally inspect the claims in the access token based on the AS that was used for the authentication (e.g getting the user name & display name claims etc.)

a.

One design might be to add a few more delegates to ClientOAuthOptions:

namespace ModelContextProtocol.Authentication;

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the delegate called when authorization server metadata is retrieved.
    /// </summary>
    public Action<AuthorizationServerMetadata> OnAuthorizationServerMetadataRetrieved { get; set; }

    /// <summary>
    /// Gets or sets the delegate called when protected resource metadata is retrieved.
    /// </summary>
    public Action<ProtectedResourceMetadata> OnProtectedResourceMetadataRetrieved { get; set; }

    ...
}

Having them as delegates/events avoids having to manage and expose state on the McpClient instance.

b.

Another design might be to use something similar to the pattern in used by ASP.NET Core auth.

namespace ModelContextProtocol.Authentication;

public sealed class RetrievingAuthorizationServerMetadataContext ...;
public sealed class RetrievedAuthorizationServerMetadataContext ...;

public sealed class RetrievingProtectedResourceMetadataContext ...;
public sealed class RetrievedProtectedResourceMetadataContext ...;

public sealed class ClientOAuthEvents
{
    /// <summary>
    /// Gets or sets the delegate called before authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievingAuthorizationServerMetadataContext, Task> OnRetrievingAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after authorization server metadata is retrieved.
    /// </summary>
    public Func<RetrievedAuthorizationServerMetadataContext, Task> OnRetrievedAuthorizationServerMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called before protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievingProtectedResourceMetadataContext, Task> OnRetrievingProtectedResourceMetadata { get; set; } = ...;

    /// <summary>
    /// Gets or sets the delegate called after protected resource metadata is retrieved.
    /// </summary>
    public Func<RetrievedProtectedResourceMetadataContext, Task> OnRetrievedProtectedResourceMetadata { get; set; } = ...;
}

public sealed class ClientOAuthOptions
{
    ...

    /// <summary>
    /// Gets or sets the <see cref="ClientOAuthEvents" />.
    /// </summary>
    public ClientOAuthEvents Events { get; set; } = new();

    ...
}

The idea behind the "Retrieving" variants is that it allows the user to implement metadata caching, although it also expands the ability for the user to shoot themselves in the foot. I suppose it depends on if caching is a user level concern or a library level concern.

The AuthorizationRedirectDelegate on ClientOAuthOptions can also be moved into the ClientOAuthEvents class to make the surface more uniform.

The overall surface may be reduced if we combine them into a single OnRetrievedMetadata and OnRetrievingMetadata, but trickiness in the contexts I suppose.