refactor: remove IVT, make HttpClient required, drop DiscoverAndRequest overload, move docs to transports.md

Author: aniket-okta

README.md

@@ -31,37 +31,10 @@ For more information about MCP:
 - [Protocol Specification](https://modelcontextprotocol.io/specification/)
 - [GitHub Organization](https://github.com/modelcontextprotocol)
 
-## Enterprise Auth / Enterprise Managed Authorization
-
-The SDK provides Cross-Application Access support for the [Identity Assertion Authorization Grant flow](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx),
-enabling enterprise SSO scenarios where users authenticate once via their enterprise Identity Provider and
-access MCP servers without per-server authorization prompts.
-
-The flow consists of two token operations:
-1. **RFC 8693 Token Exchange** at the IdP: ID Token → JWT Authorization Grant (JAG)
-2. **RFC 7523 JWT Bearer Grant** at the MCP Server: JAG → Access Token
-
-### Using CrossApplicationAccessProvider
-
-```csharp
-using ModelContextProtocol.Authentication;
-
-var provider = new CrossApplicationAccessProvider(new CrossApplicationAccessProviderOptions
-{
-    ClientId = "mcp-client-id",
-    IdpTokenEndpoint = "https://company.okta.com/oauth2/token",
-    IdpClientId = "idp-client-id",
-    IdTokenCallback = async (context, ct) =>
-    {
-        // Return the OIDC ID token from your SSO session
-        return myIdToken;
-    }
-});
-
-var tokens = await provider.GetAccessTokenAsync(
-    resourceUrl: new Uri("https://mcp-server.example.com"),
-    authorizationServerUrl: new Uri("https://auth.mcp-server.example.com"));
-```
+## Cross-Application Access (Identity Assertion Authorization Grant flow)
+
+The SDK provides support for the [Identity Assertion Authorization Grant flow](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx)
+via `CrossApplicationAccessProvider`. See the [Cross-Application Access](docs/concepts/transports/transports.md#cross-application-access) section in the transport docs for full usage details.
 
 ## License
 

docs/concepts/transports/transports.md

@@ -378,3 +378,42 @@ Console.WriteLine(await echo.InvokeAsync(new() { ["arg"] = "Hello World" }));
 ```
 
 Like [stdio](#stdio-transport), the in-memory transport is inherently single-session — there is no `Mcp-Session-Id` header, and server-to-client requests (sampling, elicitation, roots) work naturally over the bidirectional pipe. This makes it ideal for testing servers that depend on these features. See [Sessions](xref:stateless) for how session behavior varies across transports.
+
+## Cross-Application Access
+
+The SDK provides built-in support for the [Identity Assertion Authorization Grant (IDAG) flow](https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx) via `CrossApplicationAccessProvider`. This enables non-interactive enterprise SSO scenarios where users authenticate once via their enterprise Identity Provider (IdP) and access MCP servers without per-server authorization prompts.
+
+The flow consists of two steps:
+1. **RFC 8693 Token Exchange** at the enterprise IdP: OIDC ID token → JWT Authorization Grant (JAG)
+2. **RFC 7523 JWT Bearer Grant** at the MCP authorization server: JAG → access token
+
+### Usage
+
+```csharp
+using ModelContextProtocol.Authentication;
+
+// The caller owns the HttpClient lifetime.
+var httpClient = new HttpClient();
+
+var provider = new CrossApplicationAccessProvider(
+    new CrossApplicationAccessProviderOptions
+    {
+        ClientId = "mcp-client-id",
+        IdpTokenEndpoint = "https://company.okta.com/oauth2/token",
+        IdpClientId = "idp-client-id",
+        IdTokenCallback = (context, cancellationToken) =>
+            // Fetch a fresh ID token from your SSO session.
+            mySsoClient.GetIdTokenAsync(cancellationToken)
+    },
+    httpClient);
+
+var tokens = await provider.GetAccessTokenAsync(
+    resourceUrl: new Uri("https://mcp-server.example.com"),
+    authorizationServerUrl: new Uri("https://auth.mcp-server.example.com"),
+    cancellationToken: ct);
+
+// Use tokens.AccessToken to authenticate against the MCP server.
+// Call provider.InvalidateCache() to force a fresh token exchange on the next call.
+```
+
+The provider caches the resulting access token and reuses it until it expires. To force re-authentication (e.g. after a 401 response), call `provider.InvalidateCache()` before retrying.

src/ModelContextProtocol.Core/Authentication/CrossApplicationAccess.cs

@@ -14,24 +14,16 @@ internal static class CrossApplicationAccess
 {
     #region Constants
 
-    /// <summary>
-    /// Grant type URN for RFC 8693 token exchange.
-    /// </summary>
+    /// <summary>Grant type URN for RFC 8693 token exchange.</summary>
     public const string GrantTypeTokenExchange = "urn:ietf:params:oauth:grant-type:token-exchange";
 
-    /// <summary>
-    /// Grant type URN for RFC 7523 JWT Bearer authorization grant.
-    /// </summary>
+    /// <summary>Grant type URN for RFC 7523 JWT Bearer authorization grant.</summary>
     public const string GrantTypeJwtBearer = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 
-    /// <summary>
-    /// Token type URN for OpenID Connect ID Tokens (RFC 8693).
-    /// </summary>
+    /// <summary>Token type URN for OpenID Connect ID Tokens (RFC 8693).</summary>
     public const string TokenTypeIdToken = "urn:ietf:params:oauth:token-type:id_token";
 
-    /// <summary>
-    /// Token type URN for SAML 2.0 assertions (RFC 8693).
-    /// </summary>
+    /// <summary>Token type URN for SAML 2.0 assertions (RFC 8693).</summary>
     public const string TokenTypeSaml2 = "urn:ietf:params:oauth:token-type:saml2";
 
     /// <summary>
@@ -57,16 +49,15 @@ internal static class CrossApplicationAccess
     /// </summary>
     public static async Task<string> RequestJwtAuthorizationGrantAsync(
         RequestJwtAuthGrantOptions options,
+        HttpClient httpClient,
         CancellationToken cancellationToken = default)
     {
         Throw.IfNull(options);
-        Throw.IfNullOrEmpty(options.TokenEndpoint, "TokenEndpoint is required.");
-        Throw.IfNullOrEmpty(options.Audience, "Audience is required.");
-        Throw.IfNullOrEmpty(options.Resource, "Resource is required.");
-        Throw.IfNullOrEmpty(options.IdToken, "IdToken is required.");
-        Throw.IfNullOrEmpty(options.ClientId, "ClientId is required.");
-
-        var httpClient = options.HttpClient ?? new HttpClient();
+        Throw.IfNullOrWhiteSpace(options.TokenEndpoint);
+        Throw.IfNullOrWhiteSpace(options.Audience);
+        Throw.IfNullOrWhiteSpace(options.Resource);
+        Throw.IfNullOrWhiteSpace(options.IdToken);
+        Throw.IfNullOrWhiteSpace(options.ClientId);
 
         var formData = new Dictionary<string, string>
         {
@@ -123,7 +114,9 @@ public static async Task<string> RequestJwtAuthorizationGrantAsync(
 
         if (response is null)
         {
-            throw new CrossApplicationAccessException($"Failed to parse token exchange response: {responseBody}");
+            var ex = new CrossApplicationAccessException("Failed to parse token exchange response.");
+            ex.Data["ResponseBody"] = responseBody;
+            throw ex;
         }
 
         if (string.IsNullOrEmpty(response.AccessToken))
@@ -137,7 +130,7 @@ public static async Task<string> RequestJwtAuthorizationGrantAsync(
                 $"Token exchange response issued_token_type must be '{TokenTypeIdJag}', got '{response.IssuedTokenType}'.");
         }
 
-        if (!string.Equals(response.TokenType, TokenTypeNotApplicable, StringComparison.OrdinalIgnoreCase))
+        if (!string.Equals(response.TokenType, TokenTypeNotApplicable, StringComparison.Ordinal))
         {
             throw new CrossApplicationAccessException(
                 $"Token exchange response token_type must be '{TokenTypeNotApplicable}' per RFC 8693 §2.2.1, got '{response.TokenType}'.");
@@ -146,43 +139,6 @@ public static async Task<string> RequestJwtAuthorizationGrantAsync(
         return response.AccessToken;
     }
 
-    /// <summary>
-    /// Discovers the IDP's token endpoint via OAuth/OIDC metadata, then requests a JWT Authorization Grant.
-    /// Convenience wrapper over <see cref="RequestJwtAuthorizationGrantAsync"/>.
-    /// </summary>
-    public static async Task<string> DiscoverAndRequestJwtAuthorizationGrantAsync(
-        DiscoverAndRequestJwtAuthGrantOptions options,
-        CancellationToken cancellationToken = default)
-    {
-        Throw.IfNull(options);
-
-        var tokenEndpoint = options.IdpTokenEndpoint;
-
-        if (string.IsNullOrEmpty(tokenEndpoint))
-        {
-            Throw.IfNullOrEmpty(options.IdpUrl, "Either IdpUrl or IdpTokenEndpoint is required.");
-
-            var httpClient = options.HttpClient ?? new HttpClient();
-            var idpMetadata = await DiscoverAuthServerMetadataAsync(
-                new Uri(options.IdpUrl!), httpClient, cancellationToken).ConfigureAwait(false);
-
-            tokenEndpoint = idpMetadata.TokenEndpoint?.ToString()
-                ?? throw new CrossApplicationAccessException($"IDP metadata discovery for {options.IdpUrl} did not return a token_endpoint.");
-        }
-
-        return await RequestJwtAuthorizationGrantAsync(new RequestJwtAuthGrantOptions
-        {
-            TokenEndpoint = tokenEndpoint!,
-            Audience = options.Audience,
-            Resource = options.Resource,
-            IdToken = options.IdToken,
-            ClientId = options.ClientId,
-            ClientSecret = options.ClientSecret,
-            Scope = options.Scope,
-            HttpClient = options.HttpClient,
-        }, cancellationToken).ConfigureAwait(false);
-    }
-
     #endregion
 
     #region JWT Bearer Grant (RFC 7523)
@@ -193,14 +149,13 @@ public static async Task<string> DiscoverAndRequestJwtAuthorizationGrantAsync(
     /// </summary>
     public static async Task<TokenContainer> ExchangeJwtBearerGrantAsync(
         ExchangeJwtBearerGrantOptions options,
+        HttpClient httpClient,
         CancellationToken cancellationToken = default)
     {
         Throw.IfNull(options);
-        Throw.IfNullOrEmpty(options.TokenEndpoint, "TokenEndpoint is required.");
-        Throw.IfNullOrEmpty(options.Assertion, "Assertion (JAG) is required.");
-        Throw.IfNullOrEmpty(options.ClientId, "ClientId is required.");
-
-        var httpClient = options.HttpClient ?? new HttpClient();
+        Throw.IfNullOrWhiteSpace(options.TokenEndpoint);
+        Throw.IfNullOrWhiteSpace(options.Assertion);
+        Throw.IfNullOrWhiteSpace(options.ClientId);
 
         var formData = new Dictionary<string, string>
         {
@@ -253,7 +208,9 @@ public static async Task<TokenContainer> ExchangeJwtBearerGrantAsync(
 
         if (response is null)
         {
-            throw new CrossApplicationAccessException($"Failed to parse JWT bearer grant response: {responseBody}");
+            var ex = new CrossApplicationAccessException("Failed to parse JWT bearer grant response.");
+            ex.Data["ResponseBody"] = responseBody;
+            throw ex;
         }
 
         if (string.IsNullOrEmpty(response.AccessToken))
@@ -336,27 +293,4 @@ internal static async Task<AuthorizationServerMetadata> DiscoverAuthServerMetada
     }
 
     #endregion
-
-    #region Helpers
-
-    private static class Throw
-    {
-        public static void IfNull<T>(T value, [System.Runtime.CompilerServices.CallerArgumentExpression(nameof(value))] string? name = null) where T : class
-        {
-            if (value is null)
-            {
-                throw new ArgumentNullException(name);
-            }
-        }
-
-        public static void IfNullOrEmpty(string? value, string message)
-        {
-            if (string.IsNullOrEmpty(value))
-            {
-                throw new ArgumentException(message);
-            }
-        }
-    }
-
-    #endregion
 }

src/ModelContextProtocol.Core/Authentication/CrossApplicationAccessProvider.cs

@@ -31,17 +31,16 @@ namespace ModelContextProtocol.Authentication;
 /// </remarks>
 /// <example>
 /// <code>
-/// var provider = new CrossApplicationAccessProvider(new CrossApplicationAccessProviderOptions
-/// {
-///     ClientId = "mcp-client-id",
-///     IdpTokenEndpoint = "https://company.okta.com/oauth2/token",
-///     IdpClientId = "idp-client-id",
-///     IdTokenCallback = async (context, ct) =>
+/// var provider = new CrossApplicationAccessProvider(
+///     new CrossApplicationAccessProviderOptions
 ///     {
-///         // Return the ID token from your SSO session
-///         return myIdToken;
-///     }
-/// });
+///         ClientId = "mcp-client-id",
+///         IdpTokenEndpoint = "https://company.okta.com/oauth2/token",
+///         IdpClientId = "idp-client-id",
+///         IdTokenCallback = (context, ct) =>
+///             mySsoClient.GetIdTokenAsync(ct)
+///     },
+///     httpClient: myHttpClient);
 ///
 /// var tokens = await provider.GetAccessTokenAsync(
 ///     resourceUrl: new Uri("https://mcp-server.example.com"),
@@ -61,38 +60,35 @@ public sealed class CrossApplicationAccessProvider
     /// Initializes a new instance of the <see cref="CrossApplicationAccessProvider"/> class.
     /// </summary>
     /// <param name="options">Configuration for the Cross-Application Access provider.</param>
-    /// <param name="httpClient">Optional HTTP client. A default will be created if not provided.</param>
+    /// <param name="httpClient">
+    /// The HTTP client to use for token exchange requests. The caller is responsible for the lifetime of this instance.
+    /// </param>
     /// <param name="loggerFactory">Optional logger factory.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="options"/> is null.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="options"/> or <paramref name="httpClient"/> is null.</exception>
     /// <exception cref="ArgumentException">Required option values are missing.</exception>
     public CrossApplicationAccessProvider(
         CrossApplicationAccessProviderOptions options,
-        HttpClient? httpClient = null,
+        HttpClient httpClient,
         ILoggerFactory? loggerFactory = null)
     {
-        _options = options ?? throw new ArgumentNullException(nameof(options));
+        Throw.IfNull(options);
+        Throw.IfNull(httpClient);
 
-        if (string.IsNullOrEmpty(options.ClientId))
-        {
-            throw new ArgumentException("ClientId is required.", nameof(options));
-        }
-
-        if (string.IsNullOrEmpty(options.IdpClientId))
-        {
-            throw new ArgumentException("IdpClientId is required.", nameof(options));
-        }
+        Throw.IfNullOrWhiteSpace(options.ClientId);
+        Throw.IfNullOrWhiteSpace(options.IdpClientId);
 
         if (string.IsNullOrEmpty(options.IdpUrl) && string.IsNullOrEmpty(options.IdpTokenEndpoint))
         {
-            throw new ArgumentException("Either IdpUrl or IdpTokenEndpoint is required.", nameof(options));
+            throw new ArgumentException("Either IdpUrl or IdpTokenEndpoint is required.", $"{nameof(options)}.{nameof(options.IdpUrl)}");
         }
 
         if (options.IdTokenCallback is null)
         {
-            throw new ArgumentException("IdTokenCallback is required.", nameof(options));
+            throw new ArgumentNullException($"{nameof(options)}.{nameof(options.IdTokenCallback)}");
         }
 
-        _httpClient = httpClient ?? new HttpClient();
+        _options = options;
+        _httpClient = httpClient;
         _logger = (ILogger?)loggerFactory?.CreateLogger<CrossApplicationAccessProvider>() ?? NullLogger.Instance;
     }
 
@@ -154,8 +150,7 @@ public async Task<TokenContainer> GetAccessTokenAsync(
                 ClientId = _options.IdpClientId,
                 ClientSecret = _options.IdpClientSecret,
                 Scope = _options.IdpScope,
-                HttpClient = _httpClient,
-            }, cancellationToken).ConfigureAwait(false);
+            }, _httpClient, cancellationToken).ConfigureAwait(false);
 
         // Step 4: RFC 7523 JWT bearer grant — JAG → access token at the MCP authorization server
         _logger.LogDebug("Exchanging JAG for access token at {McpTokenEndpoint}", mcpTokenEndpoint);
@@ -167,8 +162,7 @@ public async Task<TokenContainer> GetAccessTokenAsync(
                 ClientId = _options.ClientId,
                 ClientSecret = _options.ClientSecret,
                 Scope = _options.Scope,
-                HttpClient = _httpClient,
-            }, cancellationToken).ConfigureAwait(false);
+            }, _httpClient, cancellationToken).ConfigureAwait(false);
 
         _cachedTokens = tokens;
         _logger.LogDebug("Cross-Application Access flow completed successfully");