Implement SEP-990 Enterprise Managed OAuth #1721

BinoyOza-okta · 2025-12-04T16:29:20Z

This PR implements the client-side components of SEP-990: Enterprise Managed Authorization. It introduces the EnterpriseAuthOAuthClientProvider to handle the full token exchange flow required for Enterprise SSO, including RFC 8693 (Token Exchange) and RFC 7523 (JWT Bearer Grant).

Motivation and Context

Implements: SEP-990

To support enterprise environments where direct API keys are not compliant, the Python SDK needs to support "Managed Authorization." This implementation allows the SDK to:

Exchange Tokens: Convert an existing Identity Provider (IdP) token (e.g., OIDC ID Token or SAML Assertion) into an MCP-specific "ID-JAG" token using RFC 8693.
Authenticate: Exchange the ID-JAG token for a usable Access Token via RFC 7523.

This aligns the Python SDK with the architecture defined in the SEP-990 implementation guide.

Implementation Details

The following components have been added to src/mcp/client/auth/extensions/enterprise_managed_auth.py:

Data Models: TokenExchangeParameters and TokenExchangeResponse using Pydantic to strictly type the exchange payloads.
Client Provider: EnterpriseAuthOAuthClientProvider, which extends the base OAuthClientProvider to orchestrate the exchange logic.
ID-JAG Logic: Support for urn:ietf:params:oauth:token-type:id-jag token types.

How Has This Been Tested?

I have implemented comprehensive unit tests in tests/client/auth/test_enterprise_managed_auth_client.py using pytest and unittest.mock.

The testing suite covers the following scenarios:

Data Model Validation:
- Verified TokenExchangeParameters correctly generates requests for both OIDC ID Tokens (test_token_exchange_params_from_id_token) and SAML Assertions (test_token_exchange_params_from_saml_assertion).
- Validated enforcement of required fields (audience, resource, subject_token).
RFC 8693 Token Exchange Logic:
- Success Path: Mocked httpx to verify the correct payload structure (grant types, token types) is sent to the IdP.
- Client Authentication: Verified that client_id and client_secret are correctly injected into the request body when configured (test_exchange_token_with_client_authentication).
- Error Handling: Validated graceful handling of HTTP 400/500 errors, non-JSON error responses, and unexpected token types.
RFC 7523 JWT Bearer Grant Logic:
- Success Path: Verified the exchange of an ID-JAG token for a final Access Token.
- Metadata Checks: Ensured the flow fails appropriately if the MCP server's OAuth metadata (token endpoint) is missing.
Network Edge Cases:
- Simulated network failures (httpx.ConnectError, httpx.ReadTimeout) to ensure OAuthTokenError is raised with descriptive messages.

Breaking Changes

No.
This is an additive extension. The core OAuthClientProvider remains backward compatible. Only users specifically importing and using EnterpriseAuthOAuthClientProvider will be affected.

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
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Dependencies: Utilizes pydantic for model validation and httpx for async requests.
Scope: As agreed, this PR includes the Client implementation (src/mcp/client/auth/extensions/).

…naged Auth support. - Written unit test cases for client and server implementation of the enterprise managed auth code.

…/extensions/enterprise_managed_auth.py 232->235, 304->307. - Resolved pre-commit errors.

…anaged auth.

maxisbey

Unless I was missing something,

src/mcp/client/auth/extensions/enterprise_managed_auth.py

tests/client/auth/test_enterprise_managed_auth_client.py

src/mcp/client/auth/extensions/enterprise_managed_auth.py

README.md

…a and JWTBearerGrantRequestData. - Added snippet file for adding code to the README.md file. - Added new section in README.md file to add information regarding: "how to use the access token once you get it" and "How does this work when the client ID is expired?".

BinoyOza-okta · 2025-12-15T05:33:00Z

Hi @maxisbey, I have addressed all your comments. Could you please review the PR?

pcarleton · 2026-01-14T11:49:57Z

Hi @BinoyOza-okta, I owe you a review on this but won't be able to get to it until Jan 23rd while I wrap up conformance tests for SDK tiering.

To make progress in the meantime, a conformance test for this feature would be really helpful to ensure the implementations are compatible across SDKs.

Cross-linking: modelcontextprotocol/typescript-sdk#1328

Thanks for your patience!

…erprise-oauth

…-990) Implements comprehensive conformance testing for enterprise managed authorization flows including RFC 8693 token exchange and RFC 7523 JWT bearer grant with ID-JAG tokens. - Add 3 conformance test scenarios to client.py: * auth/enterprise-id-jag-validation - Validates ID-JAG token structure * auth/enterprise-token-exchange - Tests OIDC ID Token → ID-JAG → Access Token flow * auth/enterprise-saml-exchange - Tests SAML Assertion → ID-JAG → Access Token flow - Create enterprise_auth_server.py: * Implements RFC 8693 token exchange endpoint (/token-exchange) * Implements RFC 7523 JWT bearer grant endpoint (/oauth/token) * Provides OAuth metadata endpoint for discovery * Supports both OIDC ID tokens and SAML assertions * Issues ID-JAG tokens with proper structure (typ: oauth-id-jag+jwt) * Validates bearer tokens and provides protected MCP endpoints - Add run-enterprise-auth-with-server.sh: * Starts mock server on port 3002 * Dynamically fetches test context * Runs all 3 enterprise auth scenarios * Reports detailed test results * Cleans up servers on exit - Update conformance.yml workflow: * Add enterprise-auth-conformance job * Runs on every pull request * Marked as optional (continue-on-error: true) * Tests run in parallel with other conformance checks - Add fastapi>=0.115.0 to dev dependencies * Required for mock server implementation * Only needed for conformance testing * Update uv.lock accordingly - Fix docstring formatting in enterprise_managed_auth_client.py: * Update get_id_token_from_idp() to follow PEP 257 (D212) * Fix multi-line docstring to start summary on first line * Apply fix to both example file and README.md * Ensures all example tests pass - Minor updates to enterprise_managed_auth.py: * Improve error handling * Add validation for token exchange parameters ✅ ID-JAG Token Validation ✅ OIDC ID Token Exchange Flow ✅ SAML Assertion Exchange Flow - RFC 8693 Token Exchange (ID Token and SAML) - RFC 7523 JWT Bearer Grant - ID-JAG token structure validation - OAuth metadata discovery - Bearer token authentication - Error handling and edge cases - SEP-990: Enterprise Managed Authorization - RFC 8693: OAuth 2.0 Token Exchange - RFC 7523: JWT Profile for OAuth 2.0 Client Authentication - RFC 8707: Resource Indicators for OAuth 2.0 Run conformance tests: ```bash ./.github/actions/conformance/run-enterprise-auth-with-server.sh

BinoyOza-okta added 14 commits November 21, 2025 17:27

- Implemented SEP-990 feature for providing support for Enterprise Ma…

f0de9e7

…naged Auth support. - Written unit test cases for client and server implementation of the enterprise managed auth code.

Added test cases for missing lines of code.

9759c7a

- Added tests cases for few of the missing lines. src/mcp/client/auth…

7f80d32

…/extensions/enterprise_managed_auth.py 232->235, 304->307. - Resolved pre-commit errors.

- Fixed pre-commit errors.

1ea72c5

- Tried to fix the ruff error.

c07b7b9

- Fixed ruff errors.

f431b54

- Removed server side changes for enterprise_managed_auth.py

d4392ae

- Added README.md changes for SEP-990 implementation for enterprise m…

db2f02c

…anaged auth.

- Resolved pyright checks error.

5fb2c0f

- Resolved README.md file fixes for removing unused imports.

005bad4

- Resolved pyright errors.

73b12b7

- Added new test cases for the missing code lines.

8214778

- Fixed the failing test cases.

04ffe5a

- Fixed the test cases.

09c05aa

felixweinberger added auth Issues and PRs related to Authentication / OAuth enhancement Request for a new feature that's not currently supported labels Dec 9, 2025

maxisbey requested a review from pcarleton December 9, 2025 15:20

maxisbey requested changes Dec 9, 2025

View reviewed changes

maxisbey added the needs more work Not ready to be merged yet, needs additional follow-up from the author(s). label Dec 10, 2025

BinoyOza-okta added 2 commits December 12, 2025 18:00

- Updated test case to include IDJAGClaims type model to verify payload.

84162df

pcarleton mentioned this pull request Jan 14, 2026

Implement SEP-990 Enterprise Managed OAuth modelcontextprotocol/typescript-sdk#1328

Open

9 tasks

BinoyOza-okta added 2 commits January 22, 2026 11:49

Merge remote-tracking branch 'upstream/main' into feature/sep-990-ent…

df471de

…erprise-oauth

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Implement SEP-990 Enterprise Managed OAuth #1721

Implement SEP-990 Enterprise Managed OAuth #1721

BinoyOza-okta commented Dec 4, 2025

Uh oh!

maxisbey left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BinoyOza-okta commented Dec 15, 2025

Uh oh!

pcarleton commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Implement SEP-990 Enterprise Managed OAuth #1721

Are you sure you want to change the base?

Implement SEP-990 Enterprise Managed OAuth #1721

Conversation

BinoyOza-okta commented Dec 4, 2025

Motivation and Context

Implementation Details

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

maxisbey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BinoyOza-okta commented Dec 15, 2025

Uh oh!

pcarleton commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants