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

[prachi-okta]

Implements Enterprise Managed Authorization (SEP-990) for the Kotlin MCP SDK

Enables MCP clients to leverage enterprise Identity Providers for seamless authorization without per-server user authentication.

Motivation and Context

Enterprise environments require OAuth flows where users authenticate with a centralized IdP, and applications need to securely access protected MCP resources on their behalf. SEP-990 addresses this via:

• Token Exchange (RFC 8693): Exchanges a user's ID token from an enterprise IdP for a JWT Authorization Grant (ID-JAG)
• JWT Bearer Grant (RFC 7523): Exchanges the ID-JAG for an access token at the MCP authorization server
• OAuth Discovery (RFC 8414): Automatically discovers authorization server metadata for both IdP and MCP servers

This follows the same provider pattern as existing auth implementations and is consistent with the Java, TypeScript, C#, and Go SDK implementations. The provider is implemented as a Ktor HttpClientPlugin that intercepts outgoing requests via HttpSend, making it a first-class citizen of the Ktor client ecosystem.

How Has This Been Tested?

Added 32 unit tests across two test classes using Kotlin Multiplatform (commonTest), Kotest assertions, and Ktor MockEngine:

EnterpriseAuthTest (20 tests):

• Authorization server metadata discovery — success via oauth-authorization-server, fallback to openid-configuration on 404/500, both-fail error, trailing slash stripping
• JAG token exchange — success, optional params in body, wrong issued_token_type throws, non-standard token_type succeeds (informational per RFC 8693 §2.2.1), missing access_token throws, HTTP error throws
• discoverAndRequestJwtAuthorizationGrant — full discovery flow, skips discovery when idpTokenEndpoint provided, no token_endpoint in metadata throws
• JWT bearer grant — success with expiresAt computed from monotonic clock, missing access_token throws, HTTP error throws
• isExpired — null expiresAt, future expiresAt, past expiresAt

EnterpriseAuthProviderTest (12 tests):

• End-to-end Authorization: Bearer header injection via Ktor plugin
• Token caching across multiple requests
• invalidateCache forces re-fetch on next request
• Discovery failure and assertion callback error propagation
• Correct resourceUrl and authorizationServerUrl passed to callback
• prepare validation — clientId null throws, assertionCallback null throws
• Blank assertion callback return throws IllegalArgumentException
• Token without expires_in cached indefinitely
• Custom expiryBuffer respected
• Full end-to-end flow — header set and token reused

Breaking Changes

None — this is a purely additive feature. No existing APIs are modified.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally (./gradlew :kotlin-sdk-client:jvmTest)
• ./gradlew apiCheck passes
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

Key design decisions:

• Ktor plugin pattern — EnterpriseAuthProvider implements HttpClientPlugin<Config, EnterpriseAuthProvider>, installed via install(EnterpriseAuthProvider) { ... } DSL; uses HttpSend interceptor for transparent header injection
• Assertion callback pattern decouples IdP interaction from the provider — callers can implement JAG caching inside the callback to reduce IdP round-trips
• client_secret_basic (Basic Auth header) used for JWT bearer grant, aligned with SEP-990 conformance requirements (RFC 6749 §2.3.1)
• token_type in JAG response is not strictly validated per RFC 8693 §2.2.1 — it is informational and strict checking rejects conformant IdPs
• Refresh tokens returned by the MCP AS are intentionally ignored — RFC 7523 is a stateless grant; using a refresh token would bypass IdP session/revocation policies
• Monotonic clock (TimeSource.Monotonic) used for token expiry to avoid wall-clock skew issues
• Double-checked locking with Mutex for thread-safe token caching on coroutines

Related SDK implementations:

• Java SDK PR: java-sdk#871
• TS SDK PR: typescript-sdk#1593
• Go SDK PR: go-sdk#770

[kpavlov]

Thank you, @prachi-okta

I see this plugin is pretty generic and does not have any MCP-specifics. Not sure if it should belong to this project.
Did you consider submitting a PR to the Ktor project instead?

cc: @e5l

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.54054% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...l/kotlin/sdk/client/auth/EnterpriseAuthProvider.kt	81.25%	7 Missing and 8 partials ⚠️
...tprotocol/kotlin/sdk/client/auth/EnterpriseAuth.kt	97.80%	0 Missing and 2 partials ⚠️
...kotlin/sdk/client/auth/JagTokenExchangeResponse.kt	66.66%	1 Missing and 1 partial ⚠️
...tocol/kotlin/sdk/client/auth/AuthServerMetadata.kt	80.00%	0 Missing and 1 partial ⚠️
...in/sdk/client/auth/JwtBearerAccessTokenResponse.kt	88.88%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!