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,

maxisbey · 2025-12-09T15:21:07Z

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

+# ============================================================================
+# Data Models
+# ============================================================================


maxisbey · 2025-12-09T15:21:52Z

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

+        redirect_handler: Any = None,
+        callback_handler: Any = None,


Can these please be correctly typed

maxisbey · 2025-12-09T15:22:47Z

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

+        token_data = {
+            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+            "requested_token_type": self.token_exchange_params.requested_token_type,
+            "audience": self.token_exchange_params.audience,
+            "resource": self.token_exchange_params.resource,
+            "subject_token": self.token_exchange_params.subject_token,
+            "subject_token_type": self.token_exchange_params.subject_token_type,
+        }


could this be typed, either a BaseModel or a TypedDict. (@Kludex would you have a preference here?)

maxisbey · 2025-12-09T15:23:31Z

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

+# ============================================================================
+# Helper Functions
+# ============================================================================


maxisbey · 2025-12-09T15:23:41Z

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

+    Note:
+        For verification, use server-side validation instead.
+    """
+    import jwt


move to top of file

maxisbey · 2025-12-09T15:24:57Z

tests/client/auth/test_enterprise_managed_auth_client.py

+# ============================================================================
+# Tests for TokenExchangeResponse
+# ============================================================================


maxisbey · 2025-12-09T15:25:02Z

tests/client/auth/test_enterprise_managed_auth_client.py

+# ============================================================================
+# Tests for IDJAGClaims
+# ============================================================================


maxisbey · 2025-12-09T15:28:16Z

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

+# ============================================================================
+
+
+def decode_id_jag(id_jag: str, verify: bool = False) -> IDJAGClaims:


verify is unused

maxisbey · 2025-12-09T15:57:31Z

README.md

+
+**Example Usage:**
+
+```python


Can this instead be put in the snippets folder and then use the scripts/update_readme_snippets.py script to update the README accordingly.

maxisbey · 2025-12-09T16:10:22Z

README.md

Need to explain how to use the access token once you get it.

How does this work when the client ID is expired?

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

maxisbey Dec 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		# ============================================================================


		def decode_id_jag(id_jag: str, verify: bool = False) -> IDJAGClaims:


		Example Usage:

		```python

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants