fix(client): preserve Cross-App IdP issuer aliases

Author: mattzcarey

.changeset/sep-2468-iss-validation.md

@@ -8,7 +8,7 @@ Add RFC 9207 `iss` parameter validation for authorization responses (SEP-2468).
 authorization server metadata before the authorization code is sent to any token endpoint (mismatch rejects the response without processing any other response parameters); `null` asserts the caller inspected the authorization response and it carried no `iss`, enabling the RFC
 9207 fail-closed rejection when the AS advertises `authorization_response_iss_parameter_supported: true`; `undefined` (omitted) skips RFC 9207 response validation, so existing `finishAuth(code)` callers that never see the authorization response are unaffected.
 
-Discovery also now validates authorization-server metadata issuer values per RFC 8414 Section 3.3. Metadata discovered for a PRM-provided authorization server URL is rejected when its `issuer` does not match that URL, and the public
-`discoverAuthorizationServerMetadata()` helper throws on mismatches or invalid issuer identifiers. Cached discovery state is also validated; stale legacy no-PRM fallback state that saved the MCP server origin before learning a distinct metadata issuer is ignored and refreshed.
-For legacy servers without protected resource metadata, metadata is still discovered at the MCP server origin; when that metadata names a distinct issuer, the SDK now treats the metadata `issuer` as the authorization server URL for persisted discovery state and fallback endpoint
-construction.
+Discovery also now validates authorization-server metadata issuer values per RFC 8414 Section 3.3. Metadata discovered for a PRM-provided authorization server URL is rejected when its `issuer` does not match that URL, and the public `discoverAuthorizationServerMetadata()` helper
+throws on mismatches or invalid issuer identifiers unless called with `{ validateIssuer: false }` for intentional alias discovery. Cached discovery state is also validated; stale legacy no-PRM fallback state that saved the MCP server origin before learning a distinct metadata
+issuer is ignored and refreshed. For legacy servers without protected resource metadata, metadata is still discovered at the MCP server origin; when that metadata names a distinct issuer, the SDK now treats the metadata `issuer` as the authorization server URL for persisted
+discovery state and fallback endpoint construction.

docs/migration-SKILL.md

@@ -515,6 +515,10 @@ members of the request/result/notification unions, the `tasks` capability key, `
 
 `Client.listPrompts()`, `listResources()`, `listResourceTemplates()`, `listTools()` now return empty results when the server lacks the corresponding capability (instead of sending the request). Set `enforceStrictCapabilities: true` in `ClientOptions` to throw an error instead.
 
+OAuth client discovery validates authorization-server metadata issuer values per RFC 8414 Section 3.3. Metadata discovered for a protected-resource metadata authorization server URL must have a matching `issuer`; cached discovery state is also revalidated. The public
+`discoverAuthorizationServerMetadata()` helper throws for mismatched or invalid issuers unless called with `{ validateIssuer: false }`. Legacy no-PRM fallback still discovers metadata at the MCP server origin and adopts a distinct valid metadata `issuer` for saved discovery
+state.
+
 ### Server (Streamable HTTP transport)
 
 No code changes required; these are wire-behavior notes:

docs/migration.md

@@ -161,7 +161,7 @@ Note: `AuthInfo` has moved from `server/auth/types.ts` to the core types and is
 
 OAuth client discovery now validates authorization-server metadata issuer values per RFC 8414 Section 3.3. When protected resource metadata identifies an authorization server URL, the discovered metadata's `issuer` must match that URL after standard URL parsing/serialization and
 trailing slash normalization. Cached discovery state is also validated; stale legacy no-PRM fallback state that saved the MCP server origin before learning a distinct metadata issuer is ignored and refreshed. The public `discoverAuthorizationServerMetadata()` helper throws when
-metadata has a mismatched or invalid issuer. If your deployment uses host aliases or proxies that serve metadata for a different issuer, publish the canonical issuer URL in protected resource metadata.
+metadata has a mismatched or invalid issuer unless called with `{ validateIssuer: false }`. If your deployment uses host aliases or proxies that serve metadata for a different issuer, publish the canonical issuer URL in protected resource metadata.
 
 For legacy MCP servers without protected resource metadata, the SDK still discovers authorization-server metadata at the MCP server origin. If that origin-hosted metadata names a distinct issuer, the SDK now treats the metadata `issuer` as the authorization server URL saved in
 discovery state and used for fallback endpoint construction.

packages/client/src/client/auth.ts

@@ -1366,19 +1366,17 @@ export interface DiscoverAuthorizationServerMetadataOptions {
     fetchFn?: FetchLike;
     /** MCP protocol version sent during metadata discovery. */
     protocolVersion?: string;
-}
-
-interface DiscoverAuthorizationServerMetadataInternalOptions extends DiscoverAuthorizationServerMetadataOptions {
+    /**
+     * Whether to validate discovered metadata's issuer against the discovery URL.
+     * Defaults to true. Set to false only when discovery intentionally starts from
+     * an alias URL whose metadata may name a canonical issuer.
+     */
     validateIssuer?: boolean;
 }
 
 async function discoverAuthorizationServerMetadataInternal(
     authorizationServerUrl: string | URL,
-    {
-        fetchFn = fetch,
-        protocolVersion = LATEST_PROTOCOL_VERSION,
-        validateIssuer = true
-    }: DiscoverAuthorizationServerMetadataInternalOptions = {}
+    { fetchFn = fetch, protocolVersion = LATEST_PROTOCOL_VERSION, validateIssuer = true }: DiscoverAuthorizationServerMetadataOptions = {}
 ): Promise<AuthorizationServerMetadata | undefined> {
     const headers = {
         'MCP-Protocol-Version': protocolVersion,
@@ -1443,7 +1441,10 @@ async function discoverAuthorizationServerMetadataInternal(
  * @param options - Configuration options
  * @param options.fetchFn - Optional fetch function for making HTTP requests, defaults to global fetch
  * @param options.protocolVersion - MCP protocol version to use, defaults to {@linkcode LATEST_PROTOCOL_VERSION}
+ * @param options.validateIssuer - Whether to validate metadata's issuer against the discovery URL, defaults to true
  * @returns Promise resolving to authorization server metadata, or undefined if discovery fails
+ * @throws {Error} If discovered metadata has an invalid issuer or the issuer does not match
+ *                 the discovery URL while issuer validation is enabled
  */
 export async function discoverAuthorizationServerMetadata(
     authorizationServerUrl: string | URL,
@@ -1538,13 +1539,18 @@ export async function discoverOAuthServerInfo(
     });
 
     if (!authorizationServerUrlFromResourceMetadata && authorizationServerMetadata) {
-        const fallbackIssuer = normalizeDiscoveredIssuerIdentifier(authorizationServerUrl, 'Authorization server URL');
-        const metadataIssuer = normalizeDiscoveredIssuerIdentifier(
-            authorizationServerMetadata.issuer,
-            'Authorization server metadata issuer'
-        );
-        if (metadataIssuer !== fallbackIssuer) {
-            authorizationServerUrl = authorizationServerMetadata.issuer;
+        try {
+            const fallbackIssuer = normalizeDiscoveredIssuerIdentifier(authorizationServerUrl, 'Authorization server URL');
+            const metadataIssuer = normalizeDiscoveredIssuerIdentifier(
+                authorizationServerMetadata.issuer,
+                'Authorization server metadata issuer'
+            );
+            if (metadataIssuer !== fallbackIssuer) {
+                authorizationServerUrl = authorizationServerMetadata.issuer;
+            }
+        } catch {
+            // Legacy no-PRM discovery intentionally disables issuer validation. Keep the
+            // fallback MCP origin when legacy metadata has an unparseable issuer value.
         }
     }
 

packages/client/src/client/crossAppAccess.ts

@@ -203,8 +203,8 @@ export async function requestJwtAuthorizationGrant(options: RequestJwtAuthGrantO
 export async function discoverAndRequestJwtAuthGrant(options: DiscoverAndRequestJwtAuthGrantOptions): Promise<JwtAuthGrantResult> {
     const { idpUrl, fetchFn = fetch, ...restOptions } = options;
 
-    // Discover IdP's authorization server metadata
-    const metadata = await discoverAuthorizationServerMetadata(String(idpUrl), { fetchFn });
+    // Enterprise IdP URLs are caller-configured and may be aliases for a canonical issuer.
+    const metadata = await discoverAuthorizationServerMetadata(String(idpUrl), { fetchFn, validateIssuer: false });
 
     if (!metadata?.token_endpoint) {
         throw new Error(`Failed to discover token endpoint for IdP: ${idpUrl}`);

packages/client/test/client/auth.test.ts

@@ -981,6 +981,23 @@ describe('OAuth Authorization', () => {
             );
         });
 
+        it('can opt out of metadata issuer validation for alias discovery', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    ...validOAuthMetadata,
+                    issuer: 'https://canonical-idp.example.com'
+                })
+            });
+
+            const metadata = await discoverAuthorizationServerMetadata('https://idp-alias.example.com', {
+                validateIssuer: false
+            });
+
+            expect(metadata?.issuer).toBe('https://canonical-idp.example.com');
+        });
+
         it('rejects OpenID metadata whose issuer does not match the authorization server URL', async () => {
             mockFetch.mockResolvedValueOnce({
                 ok: false,
@@ -1242,6 +1259,42 @@ describe('OAuth Authorization', () => {
             expect(mockFetch.mock.calls[1]![0].toString()).toBe('https://resource.example.com/.well-known/oauth-authorization-server');
         });
 
+        it('keeps the legacy fallback MCP origin when unvalidated metadata has an invalid issuer', async () => {
+            const legacyAuthMetadata = {
+                ...validAuthMetadata,
+                issuer: 'auth.example.com',
+                authorization_endpoint: 'https://resource.example.com/authorize',
+                token_endpoint: 'https://resource.example.com/token'
+            };
+
+            mockFetch.mockImplementation(url => {
+                const urlString = url.toString();
+
+                if (urlString.includes('/.well-known/oauth-protected-resource')) {
+                    return Promise.resolve({
+                        ok: false,
+                        status: 404
+                    });
+                }
+
+                if (urlString.includes('/.well-known/oauth-authorization-server')) {
+                    return Promise.resolve({
+                        ok: true,
+                        status: 200,
+                        json: async () => legacyAuthMetadata
+                    });
+                }
+
+                return Promise.reject(new Error(`Unexpected fetch: ${urlString}`));
+            });
+
+            const result = await discoverOAuthServerInfo('https://resource.example.com');
+
+            expect(result.authorizationServerUrl).toBe('https://resource.example.com/');
+            expect(result.resourceMetadata).toBeUndefined();
+            expect(result.authorizationServerMetadata).toEqual(legacyAuthMetadata);
+        });
+
         it('forwards resourceMetadataUrl override to protected resource metadata discovery', async () => {
             const overrideUrl = new URL('https://custom.example.com/.well-known/oauth-protected-resource');
 

packages/client/test/client/crossAppAccess.test.ts

@@ -265,6 +265,44 @@ describe('crossAppAccess', () => {
             expect(String(mockFetch.mock.calls[1]![0])).toBe('https://idp.example.com/token');
         });
 
+        it('allows IdP discovery aliases whose metadata names a canonical issuer', async () => {
+            const mockFetch = vi.fn<FetchLike>();
+
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    issuer: 'https://login.microsoftonline.com/tenant-guid/v2.0',
+                    authorization_endpoint: 'https://login.microsoftonline.com/tenant-guid/oauth2/v2.0/authorize',
+                    token_endpoint: 'https://login.microsoftonline.com/tenant-guid/oauth2/v2.0/token',
+                    jwks_uri: 'https://login.microsoftonline.com/tenant-guid/discovery/v2.0/keys',
+                    response_types_supported: ['code'],
+                    grant_types_supported: ['urn:ietf:params:oauth:grant-type:token-exchange']
+                })
+            } as Response);
+
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: async () => ({
+                    issued_token_type: 'urn:ietf:params:oauth:token-type:id-jag',
+                    access_token: 'jag-token',
+                    token_type: 'N_A'
+                })
+            } as Response);
+
+            const result = await discoverAndRequestJwtAuthGrant({
+                idpUrl: 'https://login.example-corp.com',
+                audience: 'https://auth.chat.example/',
+                resource: 'https://mcp.chat.example/',
+                idToken: 'id-token',
+                clientId: 'client',
+                fetchFn: mockFetch
+            });
+
+            expect(result.jwtAuthGrant).toBe('jag-token');
+            expect(String(mockFetch.mock.calls[0]![0])).toBe('https://login.example-corp.com/.well-known/oauth-authorization-server');
+            expect(String(mockFetch.mock.calls[1]![0])).toBe('https://login.microsoftonline.com/tenant-guid/oauth2/v2.0/token');
+        });
+
         it('throws error when token endpoint is not discovered', async () => {
             const mockFetch = vi.fn<FetchLike>().mockResolvedValue({
                 ok: true,

packages/codemod/src/generated/versions.ts

@@ -1,9 +1,9 @@
 // AUTO-GENERATED — do not edit. Run `pnpm run generate:versions` to regenerate.
 export const V2_PACKAGE_VERSIONS: Record<string, string> = {
-    '@modelcontextprotocol/client': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/server': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/node': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/express': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/server-legacy': '^2.0.0-alpha.2',
-    '@modelcontextprotocol/core': '^2.0.0-alpha.0'
+    '@modelcontextprotocol/client': '^2.0.0-alpha.3',
+    '@modelcontextprotocol/server': '^2.0.0-alpha.3',
+    '@modelcontextprotocol/node': '^2.0.0-alpha.3',
+    '@modelcontextprotocol/express': '^2.0.0-alpha.3',
+    '@modelcontextprotocol/server-legacy': '^2.0.0-alpha.3',
+    '@modelcontextprotocol/core': '^2.0.0-alpha.1'
 };