Authorization Server & Protected Resource Metadata inspection

Comienza con ClientOAuthOptions y la ruta del cliente MCP que obtiene los metadatos del servidor de autorización y del recurso protegido. Revisa el AuthorizationRedirectDelegate existente y el código de autenticación relacionado; después, compara los diseños propuestos de delegate y ClientOAuthEvents, incluida la cuestión de la caché. Se considera terminado cuando la API pública elegida expone de forma coherente el acceso a los metadatos solicitados y existe cobertura para los callbacks seleccionados.

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.