Implement SEP-990 Enterprise Managed OAuth

Author: sagar-okta

docs/client.md

@@ -58,3 +58,59 @@ These examples show how to:
 - Perform dynamic client registration if needed.
 - Acquire access tokens.
 - Attach OAuth credentials to Streamable HTTP requests.
+
+#### Cross-App Access Middleware
+
+The `withCrossAppAccess` middleware enables secure authentication for MCP clients accessing protected servers through OAuth-based Cross-App Access flows. It automatically handles token acquisition and adds Authorization headers to requests.
+
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { withCrossAppAccess } from '@modelcontextprotocol/client';
+
+// Configure Cross-App Access middleware
+const enhancedFetch = withCrossAppAccess({
+    idpUrl: 'https://idp.example.com',
+    mcpResourceUrl: 'https://mcp-server.example.com',
+    mcpAuthorisationServerUrl: 'https://mcp-auth.example.com',
+    idToken: 'your-id-token',
+    idpClientId: 'your-idp-client-id',
+    idpClientSecret: 'your-idp-client-secret',
+    mcpClientId: 'your-mcp-client-id',
+    mcpClientSecret: 'your-mcp-client-secret',
+    scope: ['read', 'write'] // Optional scopes
+})(fetch);
+
+// Use the enhanced fetch with your client transport
+const transport = new StreamableHTTPClientTransport(
+    new URL('https://mcp-server.example.com/mcp'),
+    enhancedFetch
+);
+
+const client = new Client({
+    name: 'secure-client',
+    version: '1.0.0'
+});
+
+await client.connect(transport);
+```
+
+The middleware performs a two-step OAuth flow:
+
+1. Exchanges your ID token for an authorization grant from the IdP
+2. Exchanges the grant for an access token from the MCP authorization server
+3. Automatically adds the access token to all subsequent requests
+
+**Configuration Options:**
+
+- **`idpUrl`**: Identity Provider's base URL for OAuth discovery
+- **`idToken`**: Identity token obtained from user authentication with the IdP
+- **`idpClientId`** / **`idpClientSecret`**: Credentials for authentication with the IdP
+- **`mcpResourceUrl`**: MCP resource server URL (used in token exchange request)
+- **`mcpAuthorisationServerUrl`**: MCP authorization server URL for OAuth discovery
+- **`mcpClientId`** / **`mcpClientSecret`**: Credentials for authentication with the MCP server
+- **`scope`**: Optional array of scope strings (e.g., `['read', 'write']`)
+
+**Token Caching:**
+
+The middleware caches the access token after the first successful exchange, so the token exchange flow only happens once. Subsequent requests reuse the cached token without additional OAuth calls.

packages/client/package.json

@@ -49,6 +49,7 @@
         "eventsource-parser": "catalog:runtimeClientOnly",
         "jose": "catalog:runtimeClientOnly",
         "pkce-challenge": "catalog:runtimeShared",
+        "qs": "catalog:runtimeClientOnly",
         "zod": "catalog:runtimeShared"
     },
     "peerDependencies": {
@@ -73,6 +74,7 @@
         "@types/content-type": "catalog:devTools",
         "@types/cross-spawn": "catalog:devTools",
         "@types/eventsource": "catalog:devTools",
+        "@types/qs": "^6.9.18",
         "@typescript/native-preview": "catalog:devTools",
         "@eslint/js": "catalog:devTools",
         "eslint": "catalog:devTools",

packages/client/src/client/middleware.ts

@@ -2,6 +2,7 @@ import type { FetchLike } from '@modelcontextprotocol/core';
 
 import type { OAuthClientProvider } from './auth.js';
 import { auth, extractWWWAuthenticateParams, UnauthorizedError } from './auth.js';
+import { getAccessToken, XAAOptions } from './xaa-util.js';
 
 /**
  * Middleware function that wraps and enhances fetch functionality.
@@ -234,6 +235,35 @@ export const withLogging = (options: LoggingOptions = {}): Middleware => {
     };
 };
 
+/**
+ * Creates a fetch wrapper that handles Cross App Access authentication automatically.
+ *
+ * This wrapper will:
+ * - Add Authorization headers with access tokens
+ *
+ * @param options - XAA configuration options
+ * @returns A fetch middleware function
+ */
+export const withCrossAppAccess = (options: XAAOptions): Middleware => {
+    return wrappedFetchFunction => {
+        let accessToken: string | undefined = undefined;
+
+        return async (url, init = {}): Promise<Response> => {
+            if (!accessToken) {
+                accessToken = await getAccessToken(options, wrappedFetchFunction);
+            }
+
+            const headers = new Headers(init.headers);
+
+            headers.set('Authorization', `Bearer ${accessToken}`);
+
+            init.headers = headers;
+
+            return wrappedFetchFunction(url, init);
+        };
+    };
+};
+
 /**
  * Composes multiple fetch middleware functions into a single middleware pipeline.
  * Middleware are applied in the order they appear, creating a chain of handlers.