feat: Add Enterprise Managed Authorization (SEP-990) support

[aniket-okta]

Implements Enterprise Managed Authorization (SEP-990) for the C# MCP SDK, enabling MCP Clients to leverage enterprise Identity Providers for seamless authorization without per-server user authentication.

Closes #949

Flow

1. SSO: User authenticates to the MCP Client via enterprise IdP (Okta, Auth0, Azure AD, etc.)
2. Token Exchange (RFC 8693): Client exchanges ID Token for Identity Assertion JWT Authorization Grant (ID-JAG) at the IdP
3. JWT Bearer Grant (RFC 7523): Client exchanges ID-JAG for Access Token at the MCP Server

Design

Layer 2: EnterpriseAuth static class : standalone utilities (~680 lines)

• RequestJwtAuthorizationGrantAsync() : RFC 8693 token exchange (ID Token → ID-JAG)
• DiscoverAndRequestJwtAuthorizationGrantAsync() : convenience wrapper with IdP discovery
• ExchangeJwtBearerGrantAsync() : RFC 7523 JWT bearer grant (ID-JAG → Access Token)
• DiscoverAuthServerMetadataAsync() : OAuth authorization server metadata discovery
• Option types: RequestJwtAuthGrantOptions, DiscoverAndRequestJwtAuthGrantOptions, ExchangeJwtBearerGrantOptions
• Response types: JagTokenExchangeResponse, JwtBearerAccessTokenResponse, OAuthErrorResponse

Layer 3: EnterpriseAuthProvider : high-level provider with caching (~230 lines)

• Assertion callback pattern decouples IdP interaction from the provider
• Automatic token caching with InvalidateCache()
• EnterpriseAuthProviderOptions for configuration (ClientId, ClientSecret, Scope, AssertionCallback)

Tests

36 unit tests covering both layers, passing on net8.0, net9.0, and net10.0.

Related

• Go SDK PR: Enterprise managed authorization go-sdk#770
• TS SDK PR: Alternative: XAA as OAuthClientProvider with Layer 2 utilities typescript-sdk#1531

[aniket-okta]

Hey @halter73, just a friendly ping on this one! It's been a few weeks since our last exchange and I wanted to check if you had any further thoughts on the token refresh / HttpMessageHandler integration question, or if the current GetAccessTokenAsync + manual ResumeSessionAsync pattern is good enough to merge as-is.

For context, both the Go (go-sdk#770) and TS (typescript-sdk#1531) PRs are still in review too, so I'm happy to align on whatever approach the team lands on across SDKs. I can also keep this PR scoped to the current API surface and follow up with a separate PR for the HttpMessageHandler helper if that's cleaner.

Happy to make any adjustments - just let me know!

[aniket-okta]

@halter73 Quick update: The TypeScript SDK's SEP-990 PR (typescript-sdk#1531) just merged! 🎉

This confirms the pattern we've implemented here is solid - token refresh via full flow re-execution, no scope step-up support, and caching with expiry checks. All aligned with how the TS SDK handles it.

[halter73]

Would it be possible to add OAuthTestBase integration test for this? You might need to add features to the TestOAuthServetlr for it, but I don't think it should be too hard. It's not like it needs to be hardened or anything

[aniket-okta]

Hi @halter73, done! Added 3 OAuthTestBase integration tests covering the full E2E flow, token caching, and cache invalidation. Also extended TestOAuthServer with the /idp/token (RFC 8693 token exchange) and jwt-bearer grant (RFC 7523) endpoints to support the tests.

One question: do we need a conformance test for this as well, or are the integration tests sufficient?

[halter73]

I wonder if we need top-level documentation for this in https://csharp.sdk.modelcontextprotocol.io/concepts/index.html. Or do we assume that each authorization provider (Entra, Okta, etc.) will provide their own docs for each SDK that's specific to their platform?

@mikekistler @jeffhandley Do you have any thoughts on this PR?

[aniket-okta]

On top-level docs:
Waiting on @mikekistler and @jeffhandley's thoughts. Happy to add a docs/concepts/ page if the team wants it, or keep it to XML API docs only.

On CI (no checks running):
I think the reason for no checks are running because the PR is from a fork and GitHub requires a maintainer to approve the first workflow run.

[aniket-okta]

The Build and Test / build (windows-latest, Debug) failure seems like a transient CI infrastructure issue.

The log shows:

vstest.console process failed to connect to testhost process after 90 seconds.
This may occur due to machine slowness, please set environment variable VSTEST_CONNECTION_TIMEOUT to increase timeout.

All tests still ran and passed despite the timeout - 0 failures across all assemblies (1922 passed in ModelContextProtocol.Tests, 336 passed in ModelContextProtocol.AspNetCore.Tests, 57 passed in Analyzers.Tests). The dotnet test process exited with code 1 due to the VSTest connection timeout event, which caused make to report Error 1. The macOS and Ubuntu Debug/Release jobs all passed cleanly.

@halter73 Could you please re-run the failed Windows Debug job? Nothing in our code changes would cause this.

[halter73]

This PR adds 8 public types here (this static class with 4 URN constants + 3 methods, the provider, its options, the assertion context, the exception, and three layer-2 option DTOs). For comparison:

• TS SDK (merged): ~4 public types.
• Go SDK (merged): just EnterpriseHandler + EnterpriseHandlerConfig — 2 public types.
• C# (this PR): 8.

I think we should try to reduce, so we can get close to Go. Concrete cuts:

1. Have the callback return an ID token (like Go's IDTokenFetcher), not a pre-fetched JAG. The provider then drives both the RFC 8693 token exchange and the RFC 7523 JWT bearer grant internally.
2. Demote this static class, its URN constants, and the three layer-2 option DTOs (RequestJwtAuthGrantOptions, DiscoverAndRequestJwtAuthGrantOptions, ExchangeJwtBearerGrantOptions) to internal.
3. Fold the IdP discovery config (IdpUrl/IdpTokenEndpoint, IdP client id/secret, scopes) into the single CrossApplicationAccessProviderOptions.

Lands us at 3 required public types (CrossApplicationAccessProvider, CrossApplicationAccessProviderOptions, CrossApplicationAccessException), plus optionally CrossApplicationAccessContext and the named delegate I called out on the provider file — 3–5 instead of 8.

Trade-off: the current "bring your own JAG" extension point goes away unless we re-expose helpers later. Given no one is asking for that today and we can promote back to public non-breakingly, the smaller surface is the right starting point.

[halter73]

Thanks for sticking with this! Two things before merge:

1. A couple of earlier review threads were marked "Done" but weren't actually finished:

• One top-level class per file - EnterpriseAuthProvider.cs still defines three top-level public types (EnterpriseAuthAssertionContext, EnterpriseAuthProvider, EnterpriseAuthProviderOptions), and EnterpriseAuth.cs still defines three internal response classes alongside the static helper. See inline comments for the splits.
• Remove SEP-990 references — still present in EnterpriseAuth.cs:51, McpJsonUtilities.cs:190, and README.md lines 34/36. Inline comments below.

2. Naming + public surface area.. Picking up the thread I left at #1305 (comment), I'd like to land on CrossApplicationAccess* (TS-aligned, no abbreviations) and significantly shrink the public surface to match the Go SDK's 2-type shape. Details inline on EnterpriseAuth.cs.

Also withdrawing my earlier "consider this authentication, not authorization" aside — see the inline comment for why.

Requesting changes on the naming + visibility decision so we don't ship a public API we can't easily walk back.

[aniket-okta]

Hey @halter73, I've addressed all of your review feedback. Here's a summary of what changed:

Naming / file structure

• Renamed everything from EnterpriseAuth* → CrossApplicationAccess* (no abbreviations, matching your guidance)
• Split every type into its own file (one-type-per-file convention)
• Renamed test files accordingly: EnterpriseAuthTests.cs → CrossApplicationAccessTests.cs, EnterpriseAuthIntegrationTests.cs → CrossApplicationAccessIntegrationTests.cs

Public surface reduction

• RequestJwtAuthGrantOptions, DiscoverAndRequestJwtAuthGrantOptions, ExchangeJwtBearerGrantOptions → all made internal sealed
• The CrossApplicationAccess static class (was EnterpriseAuth) → internal
• JagTokenExchangeResponse, JwtBearerAccessTokenResponse, OAuthErrorResponse → split out and made internal sealed
• Added InternalsVisibleTo in ModelContextProtocol.Core.csproj for both test assemblies

Callback simplification

• IdTokenCallback now returns Task<string> (just the ID token string): the provider drives RFC 8693 and RFC 7523 internally, so callers don't need to know about those flows
• Introduced a named delegate CrossApplicationAccessIdTokenCallback in its own file (modeled on AuthorizationRedirectDelegate)
• Folded IdP config (IdpUrl/IdpTokenEndpoint, IdpClientId, IdpClientSecret, IdpScope) directly into CrossApplicationAccessProviderOptions: no separate IdP options class

SEP-990 / spec reference cleanup

• Removed all SEP-990 references from public-facing files (XML docs, McpJsonUtilities.cs, README.md, test comments)
• Replaced with a link to the official ext-auth spec: https://github.com/modelcontextprotocol/ext-auth/blob/main/specification/draft/enterprise-managed-authorization.mdx

Context type

• EnterpriseAuthAssertionContext → CrossApplicationAccessContext with required Uri ResourceUrl and required Uri AuthorizationServerUrl

Let me know if anything else needs adjusting!

[halter73]

Thanks for the rename and the file split. The public surface (CrossApplicationAccess*) reads much better now.

That said, the PR has grown rather than shrunk in this round, and most of the new weight is testing internals rather than behavior. Before another pass I'd like to see the surface area pulled back and a few correctness/lifecycle issues addressed. Grouping the asks below so it's easier to triage:

Please remove

• InternalsVisibleTo for both test assemblies in ModelContextProtocol.Core.csproj. We intentionally do not use IVT in this repo (see #6 — it was one of the first things we removed after migrating to the modelcontextprotocol org). If a test can't be expressed against the public API, just delete it.
• The nested Throw helper class in CrossApplicationAccess.cs. src/Common/Throw.cs is already linked into Core (<Compile Include="..\Common\Throw.cs" Link="Throw.cs" />) and provides Throw.IfNull (with [NotNull] + CallerArgumentExpression) and Throw.IfNullOrWhiteSpace. Use those everywhere instead — including replacing the manual string.IsNullOrEmpty(...) → throw new ArgumentException(...) blocks in the CrossApplicationAccessProvider constructor.
• The unused DiscoverAndRequestJwtAuthorizationGrantAsync overload (and its DiscoverAndRequestJwtAuthGrantOptions DTO, and the 4 unit tests targeting it). With CrossApplicationAccess now internal, that method has no callers — the production flow goes through CrossApplicationAccessProvider.ResolveIdpTokenEndpointAsync instead. Once IVT is gone, the corresponding tests must go too.
• The leftover "Enterprise" wording in README.md (heading on line 34) and the async lambda on line 57 that doesn't await.

Please change

• HttpClient should be a required, non-nullable constructor parameter on CrossApplicationAccessProvider, not HttpClient? httpClient = null with a ?? new HttpClient() fallback. The owning caller (e.g. HttpClientTransport) is responsible for the HttpClient lifetime — this is exactly the pattern ClientOAuthProvider uses (see ClientOAuthProvider.cs:62). Apply the same fix to the internal CrossApplicationAccess helpers that also do httpClient ?? new HttpClient().
• Don't echo raw HTTP response bodies into CrossApplicationAccessException.Message. Keep the exception message to a short, sanitized summary (status code + endpoint).
• The new docs roughly double the README size. Please move the bulk of it under docs/ (see the inline suggestion on line 65 for where).

Out of scope for this PR

The cache fields on CrossApplicationAccessProvider aren't thread-safe — but neither are ClientOAuthProvider._tokenCache / _authServerMetadata, nor the equivalents in the TS (CrossAppAccessProvider._tokens) and Go (EnterpriseHandler.tokenSource) SDKs. Since this is a pre-existing gap shared across providers (and SDKs) rather than something this PR introduces, I'd rather address it as a single follow-up that covers both C# providers and aligns with whatever TS/Go land on. Tracked in #1595 — no action needed in this PR.

Once the surface is trimmed and the HttpClient lifecycle matches ClientOAuthProvider, this should be in good shape.

[halter73]

And I hate to circle back on the naming, but I don't love CrossApplication* either despite having been the person to suggest it. It still feels super generic — OAuth is designed to provide access across applications in general, whether you're using an authorization code flow or ID-JAG client assertions. I only suggested it because the TS SDK used crossApp as a prefix and it seemed like the most direct transliteration into C# naming conventions.

But now I notice that Go went with EnterpriseHandler and the Python PR at modelcontextprotocol/python-sdk#1721 is currently using EnterpriseAuthOAuthClientProvider. To be clear, I'm not suggesting we go back to something as generic as EnterpriseAuthProvider. But if we're going to be inconsistent with the other SDKs anyway, can we pick something more specific?

A couple of options to consider, in rough order of my preference:

• IdJagAccessProvider — names the actual mechanism, matches the spec terminology
• IdentityAssertionGrantProvider — spells out the acronym (matching our "App → Application" convention) and is exactly the section heading in SEP-990.
• IdJagProvider — concise, but undersells the whole three-step flow.

I do see that CrossApplicationAccess matches what the SEP-990 conformance test framework calls the flow externally, so devs hunting for "SEP-990 in C#" might find it more easily. With an ID-JAG name we lean more on the spec internals, but I think that's an acceptable tradeoff for a less generic name.

Edit: To be clear, I'm not going to hold up the PR on this. I'll merge with the current naming if we can't agree on something better, but I do think we can come up with something better.

[aniket-okta]

@halter73 Thanks for the follow-up on naming completely agree that CrossApplication* is too generic in hindsight.
Of your three options, I think IdentityAssertionGrantProvider is the strongest fit:

• It's the exact section heading in the SEP-990 spec ("Identity Assertion Authorization Grant"), so it's discoverable from the spec side
• "Assertion" immediately signals this is assertion-based auth, distinguishing it from interactive OAuth at a glance
• It follows our App → Application no-abbreviation convention cleanly throughout: IdentityAssertionGrantProvider, IdentityAssertionGrantProviderOptions, IdentityAssertionGrantContext, IdentityAssertionGrantIdTokenCallback
• It's more specific than CrossApplication* without being as opaque as IdJag* to a developer who hasn't read the spec
  IdJagAccessProvider is precise but mixes an unexpanded acronym with a plain word, and IdJagProvider undersells the three-step flow as you noted.

One thing worth flagging: from Okta's side, this feature is publicly marketed and documented as "Cross-Application Access" and "Enterprise Auth" those are the terms in our product docs, customer-facing guides, and related PRs across SDKs (Go, Python, TS). That's partly why those names surfaced here. So if discoverability for Okta customers integrating with MCP is a concern, CrossApplication* has real value developers following Okta docs will land on the right API immediately. That said, I understand the SDK should be vendor-neutral, and IdentityAssertionGrant* achieves that while staying spec-grounded.

Happy to do the rename to IdentityAssertionGrant* in this PR if you agree it's a pure find-and-replace across the ~10 files we already split out. Or if you'd prefer to merge with CrossApplication* and rename in a follow-up, that works too.

On the other review items addressed in the latest push:

• InternalsVisibleTo removed from the csproj
• Nested Throw helper replaced with Throw.IfNull/Throw.IfNullOrWhiteSpace from Throw.cs
• DiscoverAndRequestJwtAuthorizationGrantAsync overload + DiscoverAndRequestJwtAuthGrantOptions.cs deleted
• HttpClient is now a required non-nullable constructor parameter (matches ClientOAuthProvider pattern), no more ?? new HttpClient()
• Raw response bodies moved to ex.Data["ResponseBody"] instead of Exception.Message
• StringComparison.Ordinal for the "N_A" token type check
• README slimmed down; full docs moved to transports.md

[halter73]

Of your three options, I think IdentityAssertionGrantProvider is the strongest fit

Sounds good! Let's go with IdentityAssertionGrantProvider. Your reasoning is solid: it matches the SEP-990 section heading, follows our no-abbreviations convention, and "Assertion" makes the auth model obvious without forcing developers to expand IdJag in their heads.

For the full rename, please also bring along:

• IdentityAssertionGrantProviderOptions
• IdentityAssertionGrantContext
• IdentityAssertionGrantIdTokenCallback
• The internal helpers in CrossApplicationAccess.cs (rename the file + static class to IdentityAssertionGrant)
• CrossApplicationAccessException → IdentityAssertionGrantException
• Test files (CrossApplicationAccessTests.cs → IdentityAssertionGrantTests.cs, and the integration test equivalent)
• README + docs/concepts/transports/transports.md references and the ## Cross-Application Access section heading

Regarding Okta's marketing terms. That's a fair point. If you want to mention "Cross Application Access" or "Enterprise Auth" we can preserve discoverability in the XML doc comments and the docs page. We can even call out Okta. (e.g. "Implements Okta's Cross-Application Access / Identity Assertion Authorization Grant flow"). The type names themselves should track the spec. Thanks for going through all the back and forth on this.

I think we'll be ready to merge after this final rename and fixing the netstandard build error.

[aaronpk]

Please note that "Cross App Access" is not an Okta term, it's just that Okta has been doing a lot of press about it. So please don't call it "Okta's Cross App Access". We updated the spec to be more explicit about that name and it now is referenced in the abstract.

https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-04.html

[aniket-okta]

Done! Here's what was addressed:

• Renamed all CrossApplicationAccess* types → [IdentityAssertionGrant*] including test files and docs

• Fixed CS8603 (netstandard2.0 build failure): added ! null-forgiving operator on [_options.IdpTokenEndpoint]( lacks [NotNullWhen(false)] on that TFM

[halter73]

I filed #1617 and #1618 as follow ups. I'm good to merge it if you are @aniket-okta. Just let me know if I'm right that IDAG should be ID-JAG in transports.md.

[aniket-okta]

Fixed — changed IDAG to ID-JAG in transports.md to match the community shorthand for the IETF draft. Ready to merge whenever you are! 🚀

[halter73]

Thanks for addressing the multiple rounds of feedback. Much appreciated!