feat(client,core): RFC 9207 iss parameter validation on authorization responses (SEP-2468)

- Add authorization_response_iss_parameter_supported to OAuthMetadataSchema
  and OpenIdProviderMetadataSchema (RFC 8414 / RFC 9207)
- New exported validateAuthorizationResponseIssuer() implementing the
  RFC 9207 Section 2.4 decision table with exact string comparison
- auth() accepts optional iss, validated against the recorded AS metadata
  before the authorization code is sent to any token endpoint
- finishAuth(code, { iss }) optional second argument on both
  StreamableHTTPClientTransport and SSEClientTransport
- Tests covering all four decision-table rows and the
  error-response-mismatch case

Closes #2197

Author: mattzcarey

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

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/client': minor
+---
+
+Add RFC 9207 `iss` parameter validation for authorization responses (SEP-2468). `OAuthMetadataSchema` and `OpenIdProviderMetadataSchema` now recognize `authorization_response_iss_parameter_supported`. The client exports a new `validateAuthorizationResponseIssuer()` helper, `auth()` accepts an optional `iss`, and `StreamableHTTPClientTransport.finishAuth()` / `SSEClientTransport.finishAuth()` accept an optional `{ iss }` second argument. When provided, the `iss` from the authorization response is validated against the issuer recorded in the authorization server metadata before the authorization code is sent to any token endpoint; on mismatch the response is rejected without processing any other response parameters. All additions are backwards-compatible.

packages/client/src/client/auth.ts

@@ -531,6 +531,53 @@ export async function parseErrorResponse(input: Response | string): Promise<OAut
     }
 }
 
+/**
+ * Validates the `iss` parameter of an authorization response against the issuer
+ * recorded from the authorization server's validated metadata, per RFC 9207
+ * (OAuth 2.0 Authorization Server Issuer Identification) Section 2.4.
+ *
+ * Decision table:
+ * 1. The AS metadata advertises `authorization_response_iss_parameter_supported: true`
+ *    but the response carries no `iss` → reject.
+ * 2. The response carries an `iss` (whether or not support was advertised) → it must be
+ *    an exact, character-by-character match of the recorded issuer (no normalization) —
+ *    mismatch → reject.
+ * 3. Support is not advertised and no `iss` is present → proceed (validation not possible).
+ * 4. On rejection, callers MUST NOT process the rest of the authorization response
+ *    (including any `error`/`error_description` parameters).
+ *
+ * @param metadata - The authorization server metadata recorded before the redirect, if available
+ * @param iss - The `iss` parameter received in the authorization response, if any
+ * @throws Error if the response must be rejected per RFC 9207
+ */
+export function validateAuthorizationResponseIssuer(
+    metadata: { issuer: string; authorization_response_iss_parameter_supported?: boolean } | undefined,
+    iss: string | undefined
+): void {
+    if (iss === undefined) {
+        if (metadata?.authorization_response_iss_parameter_supported === true) {
+            throw new Error(
+                'Authorization server metadata advertises authorization_response_iss_parameter_supported, but the authorization response did not include an iss parameter (RFC 9207)'
+            );
+        }
+        // Neither advertised nor present: validation is not possible; proceed.
+        return;
+    }
+
+    if (metadata === undefined) {
+        throw new Error(
+            'Authorization response included an iss parameter, but no authorization server metadata was recorded to validate it against (RFC 9207)'
+        );
+    }
+
+    // Exact string comparison — no normalization of any kind (RFC 9207 Section 2.4).
+    if (iss !== metadata.issuer) {
+        throw new Error(
+            `Authorization response iss parameter does not match the expected issuer: expected ${metadata.issuer}, got ${iss} (RFC 9207). The authorization response must not be processed.`
+        );
+    }
+}
+
 /**
  * Orchestrates the full auth flow with a server.
  *
@@ -542,6 +589,12 @@ export async function auth(
     options: {
         serverUrl: string | URL;
         authorizationCode?: string;
+        /**
+         * The `iss` parameter received alongside the authorization code in the
+         * authorization response, validated per RFC 9207 against the issuer recorded
+         * in the authorization server metadata before the code is exchanged.
+         */
+        iss?: string;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -603,12 +656,14 @@ async function authInternal(
     {
         serverUrl,
         authorizationCode,
+        iss,
         scope,
         resourceMetadataUrl,
         fetchFn
     }: {
         serverUrl: string | URL;
         authorizationCode?: string;
+        iss?: string;
         scope?: string;
         resourceMetadataUrl?: URL;
         fetchFn?: FetchLike;
@@ -747,6 +802,12 @@ async function authInternal(
 
     // Exchange authorization code for tokens, or fetch tokens directly for non-interactive flows
     if (authorizationCode !== undefined || nonInteractiveFlow) {
+        if (authorizationCode !== undefined) {
+            // RFC 9207: validate the authorization response issuer against the recorded
+            // AS metadata BEFORE the code is sent to any token endpoint.
+            validateAuthorizationResponseIssuer(metadata, iss);
+        }
+
         const tokens = await fetchToken(provider, authorizationServerUrl, {
             metadata,
             resource,

packages/client/src/client/sse.ts

@@ -228,15 +228,21 @@ export class SSEClientTransport implements Transport {
 
     /**
      * Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.
+     *
+     * @param authorizationCode - The authorization code from the authorization response
+     * @param options.iss - The `iss` parameter from the authorization response, if present.
+     * Validated against the issuer recorded in the authorization server metadata per RFC 9207
+     * before the code is exchanged.
      */
-    async finishAuth(authorizationCode: string): Promise<void> {
+    async finishAuth(authorizationCode: string, options?: { iss?: string }): Promise<void> {
         if (!this._oauthProvider) {
             throw new UnauthorizedError('finishAuth requires an OAuthClientProvider');
         }
 
         const result = await auth(this._oauthProvider, {
             serverUrl: this._url,
             authorizationCode,
+            iss: options?.iss,
             resourceMetadataUrl: this._resourceMetadataUrl,
             scope: this._scope,
             fetchFn: this._fetchWithInit

packages/client/src/client/streamableHttp.ts

@@ -489,15 +489,21 @@ export class StreamableHTTPClientTransport implements Transport {
 
     /**
      * Call this method after the user has finished authorizing via their user agent and is redirected back to the MCP client application. This will exchange the authorization code for an access token, enabling the next connection attempt to successfully auth.
+     *
+     * @param authorizationCode - The authorization code from the authorization response
+     * @param options.iss - The `iss` parameter from the authorization response, if present.
+     * Validated against the issuer recorded in the authorization server metadata per RFC 9207
+     * before the code is exchanged.
      */
-    async finishAuth(authorizationCode: string): Promise<void> {
+    async finishAuth(authorizationCode: string, options?: { iss?: string }): Promise<void> {
         if (!this._oauthProvider) {
             throw new UnauthorizedError('finishAuth requires an OAuthClientProvider');
         }
 
         const result = await auth(this._oauthProvider, {
             serverUrl: this._url,
             authorizationCode,
+            iss: options?.iss,
             resourceMetadataUrl: this._resourceMetadataUrl,
             scope: this._scope,
             fetchFn: this._fetchWithInit

packages/client/src/index.ts

@@ -35,6 +35,7 @@ export {
     selectResourceURL,
     startAuthorization,
     UnauthorizedError,
+    validateAuthorizationResponseIssuer,
     validateClientMetadataUrl
 } from './client/auth.js';
 export type {

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

@@ -19,6 +19,7 @@ import {
     registerClient,
     selectClientAuthMethod,
     startAuthorization,
+    validateAuthorizationResponseIssuer,
     validateClientMetadataUrl
 } from '../../src/client/auth.js';
 import { createPrivateKeyJwtAuth } from '../../src/client/authExtensions.js';
@@ -4131,3 +4132,223 @@ describe('OAuth Authorization', () => {
         });
     });
 });
+
+describe('SEP-2468: RFC 9207 authorization response iss validation', () => {
+    const issuer = 'https://auth.example.com';
+
+    describe('validateAuthorizationResponseIssuer', () => {
+        // RFC 9207 Section 2.4, row 1: advertised but absent -> reject
+        it('rejects when the AS advertises iss support but the response lacks iss', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: true }, undefined)
+            ).toThrow(/did not include an iss parameter/);
+        });
+
+        // RFC 9207 Section 2.4, row 2: present (advertised) -> exact match required
+        it('accepts an exactly matching iss when support is advertised', () => {
+            expect(() =>
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: true }, issuer)
+            ).not.toThrow();
+        });
+
+        // RFC 9207 Section 2.4, row 2: present even without advertisement -> still compared
+        it('accepts an exactly matching iss even when support is not advertised', () => {
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, issuer)).not.toThrow();
+        });
+
+        it('rejects a mismatched iss regardless of advertisement', () => {
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, 'https://attacker.example.com')).toThrow(
+                /does not match the expected issuer/
+            );
+            expect(() =>
+                validateAuthorizationResponseIssuer(
+                    { issuer, authorization_response_iss_parameter_supported: true },
+                    'https://attacker.example.com'
+                )
+            ).toThrow(/does not match the expected issuer/);
+        });
+
+        it('uses exact string comparison with no normalization', () => {
+            // Trailing slash and case differences are equivalent URLs but MUST be rejected
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, `${issuer}/`)).toThrow(/does not match the expected issuer/);
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, 'https://AUTH.example.com')).toThrow(
+                /does not match the expected issuer/
+            );
+        });
+
+        // RFC 9207 Section 2.4, row 3: neither advertised nor present -> proceed
+        it('proceeds when iss support is not advertised and no iss is present', () => {
+            expect(() => validateAuthorizationResponseIssuer({ issuer }, undefined)).not.toThrow();
+            expect(() =>
+                validateAuthorizationResponseIssuer({ issuer, authorization_response_iss_parameter_supported: false }, undefined)
+            ).not.toThrow();
+        });
+
+        it('proceeds when no metadata is recorded and no iss is present', () => {
+            expect(() => validateAuthorizationResponseIssuer(undefined, undefined)).not.toThrow();
+        });
+
+        it('rejects when an iss is present but no metadata was recorded to validate against', () => {
+            expect(() => validateAuthorizationResponseIssuer(undefined, issuer)).toThrow(/no authorization server metadata was recorded/);
+        });
+    });
+
+    describe('auth() with an authorization code', () => {
+        const resourceMetadata = {
+            resource: 'https://resource.example.com',
+            authorization_servers: [issuer]
+        };
+
+        const authServerMetadata: AuthorizationServerMetadata = {
+            issuer,
+            authorization_endpoint: `${issuer}/authorize`,
+            token_endpoint: `${issuer}/token`,
+            response_types_supported: ['code'],
+            code_challenge_methods_supported: ['S256'],
+            authorization_response_iss_parameter_supported: true
+        };
+
+        function createMockProvider(metadata: AuthorizationServerMetadata = authServerMetadata): OAuthClientProvider {
+            return {
+                get redirectUrl() {
+                    return 'http://localhost:3000/callback';
+                },
+                get clientMetadata() {
+                    return {
+                        redirect_uris: ['http://localhost:3000/callback'],
+                        client_name: 'Test Client'
+                    };
+                },
+                clientInformation: vi.fn().mockResolvedValue({
+                    client_id: 'test-client-id',
+                    client_secret: 'test-client-secret'
+                }),
+                tokens: vi.fn().mockResolvedValue(undefined),
+                saveTokens: vi.fn(),
+                redirectToAuthorization: vi.fn(),
+                saveCodeVerifier: vi.fn(),
+                codeVerifier: vi.fn().mockResolvedValue('test-verifier'),
+                // Discovery state recorded before the redirect, including the validated issuer
+                discoveryState: vi.fn().mockResolvedValue({
+                    authorizationServerUrl: issuer,
+                    resourceMetadata,
+                    authorizationServerMetadata: metadata
+                })
+            };
+        }
+
+        beforeEach(() => {
+            mockFetch.mockReset();
+            mockFetch.mockImplementation(url => {
+                const urlString = url.toString();
+                if (urlString.includes('/token')) {
+                    return Promise.resolve({
+                        ok: true,
+                        status: 200,
+                        json: async () => ({
+                            access_token: 'access123',
+                            token_type: 'Bearer',
+                            expires_in: 3600
+                        })
+                    });
+                }
+                return Promise.reject(new Error(`Unexpected fetch: ${urlString}`));
+            });
+        });
+
+        function tokenEndpointCalls(): unknown[][] {
+            return mockFetch.mock.calls.filter(call => call[0].toString().includes('/token'));
+        }
+
+        it('exchanges the code when the response iss matches the recorded issuer', async () => {
+            const provider = createMockProvider();
+
+            const result = await auth(provider, {
+                serverUrl: 'https://resource.example.com',
+                authorizationCode: 'code123',
+                iss: issuer
+            });
+
+            expect(result).toBe('AUTHORIZED');
+            expect(tokenEndpointCalls()).toHaveLength(1);
+            expect(provider.saveTokens).toHaveBeenCalled();
+        });
+
+        it('rejects a mismatched iss before the code reaches any token endpoint', async () => {
+            const provider = createMockProvider();
+
+            await expect(
+                auth(provider, {
+                    serverUrl: 'https://resource.example.com',
+                    authorizationCode: 'code123',
+                    iss: 'https://attacker.example.com'
+                })
+            ).rejects.toThrow(/does not match the expected issuer/);
+
+            expect(tokenEndpointCalls()).toHaveLength(0);
+            expect(provider.saveTokens).not.toHaveBeenCalled();
+        });
+
+        it('rejects when the AS advertises iss support but no iss is provided', async () => {
+            const provider = createMockProvider();
+
+            await expect(
+                auth(provider, {
+                    serverUrl: 'https://resource.example.com',
+                    authorizationCode: 'code123'
+                })
+            ).rejects.toThrow(/did not include an iss parameter/);
+
+            expect(tokenEndpointCalls()).toHaveLength(0);
+        });
+
+        it('proceeds without an iss when the AS does not advertise support', async () => {
+            const provider = createMockProvider({
+                ...authServerMetadata,
+                authorization_response_iss_parameter_supported: undefined
+            });
+
+            const result = await auth(provider, {
+                serverUrl: 'https://resource.example.com',
+                authorizationCode: 'code123'
+            });
+
+            expect(result).toBe('AUTHORIZED');
+            expect(tokenEndpointCalls()).toHaveLength(1);
+        });
+
+        it('does not surface error content from a mismatched-issuer error response', async () => {
+            // RFC 9207: on issuer mismatch the client MUST NOT process the rest of the
+            // authorization response — including error/error_description parameters.
+            // Simulate a forged callback carrying both a mismatched iss and attacker-
+            // controlled error content alongside the code.
+            const forgedAuthorizationResponse = {
+                code: 'code123',
+                iss: 'https://attacker.example.com',
+                error: 'access_denied',
+                error_description: 'ATTACKER CONTROLLED MESSAGE'
+            };
+
+            const provider = createMockProvider();
+
+            const error = await auth(provider, {
+                serverUrl: 'https://resource.example.com',
+                authorizationCode: forgedAuthorizationResponse.code,
+                iss: forgedAuthorizationResponse.iss
+            }).then(
+                () => {
+                    throw new Error('expected auth() to reject');
+                },
+                (e: unknown) => e as Error
+            );
+
+            // Rejected for the issuer mismatch, without echoing the forged error params
+            expect(error.message).toMatch(/does not match the expected issuer/);
+            expect(error.message).not.toContain(forgedAuthorizationResponse.error_description);
+            expect(error.message).not.toContain('access_denied');
+
+            // And the code was never sent to a token endpoint
+            expect(tokenEndpointCalls()).toHaveLength(0);
+        });
+    });
+});