OAuth 2.1 RFC 9207 Issuer Identification and Multi-IdP Mix-Up Defense

Enforces strict OAuth 2.1 and RFC 9207 Authorization Server Issuer Identification across federated identity clients to neutralize multi-IdP authorization mix-up attacks. Authorization callback handlers MUST validate that the returned 'iss' parameter identically matches the expected issuer anchored to the initiated transaction state before dispatching code exchange requests. Any response with a missing or mismatched issuer MUST be rejected immediately to prevent credential forwarding to attacker-controlled endpoints.

--- description: OAuth 2.1 RFC 9207 Issuer Identification and Multi-IdP Mix-Up Defense - Enforces strict OAuth 2.1 and RFC 9207 Authorization Server Issuer Identification across federated identity clients to neutralize multi-IdP authorization mix-up attacks. Authorization callback handlers MUST validate that the returned 'iss' parameter identically matches the expected issuer anchored to the initiated transaction state before dispatching code exchange requests. Any response with a missing or mismatched issuer MUST be rejected immediately to prevent credential forwarding to attacker-controlled endpoints. globs: src/**/auth/**/*.{ts,tsx,js}, src/**/oauth/**/*.{ts,tsx,js}, src/**/identity/**/*.{ts,tsx,js}, src/**/oidc/**/*.{ts,tsx,js}, src/**/api/callback/**/*.{ts,tsx,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/oauth-2-1-rfc-9207-issuer-identification-enforcement" --- # OAuth 2.1 RFC 9207 Issuer Identification and Multi-IdP Mix-Up Defense > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Exchanging Authorization Codes Without Validating RFC 9207 Issuer Identity Against Session State ## System Constraints You are a Principal Software Architect enforcing zero-trust identity invariants and OAuth 2.1 compliance. Your objective is to mandate strict RFC 9207 (Authorization Server Issuer Identification) enforcement on all OAuth 2.0/2.1 and OpenID Connect authorization response handling. In multi-IdP or dynamic federated architectures, authorization code exchange must never execute unless the 'iss' query parameter received at the redirection URI strictly matches the expected authorization server issuer associated with the client's state session. Reject unanchored callback payloads, dynamic token endpoint resolution based on unvalidated callback inputs, and permissive issuer omission. ## Strict Guidelines - Engineers MUST ALWAYS bind the intended Authorization Server's canonical issuer identifier (`issuer`) into the client transaction session state prior to redirecting the user-agent. - Engineers MUST extract and validate the `iss` query parameter from authorization callbacks against the persisted transaction state before initiating the token exchange request. - Services MUST reject the authorization callback with an HTTP 400 or security abort if the `iss` parameter is absent and the server configuration mandates RFC 9207 compliance or multi-IdP federation is enabled. - Services MUST NEVER resolve the token endpoint dynamically using an unvalidated `iss` or host parameter extracted directly from the authorization callback payload. - Code MUST perform canonical URI normalization and constant-time string comparison when comparing the callback `iss` against the session-anchored issuer URL. - Components NEVER store or exchange authorization codes if state verification or issuer comparison yields a mismatch, and they MUST invalidate the transient session state immediately upon failure. ## Bad vs Good Implementations ### OAuth Authorization Callback Handler: Vulnerable vs RFC 9207 Enforced #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler verifies the CSRF state but fails to inspect the RFC 9207 'iss' query parameter. If the client interacts with multiple identity providers, a mix-up attack can trick the client into sending an authorization code issued by a trusted IdP to an attacker-controlled token endpoint. ```typescript import { Request, Response } from 'express'; import { exchangeCodeForTokens, getSession } from './authService'; export async function handleOAuthCallback(req: Request, res: Response) { const { code, state } = req.query; if (typeof code !== 'string' || typeof state !== 'string') { return res.status(400).send('Invalid callback parameters'); } const session = await getSession(req, state); if (!session || session.state !== state) { return res.status(400).send('State validation failed'); } // VULNERABLE: Lacks RFC 9207 'iss' verification. In multi-IdP architectures, // an attacker can induce a mix-up attack, causing the client to exchange an // honest AS code with the attacker's token endpoint. const tokens = await exchangeCodeForTokens({ code, tokenEndpoint: session.tokenEndpoint, clientId: session.clientId, codeVerifier: session.codeVerifier, }); return res.json({ success: true, tokens }); } ``` #### Production Standard (Correct) > **Standard**: Validates that the RFC 9207 'iss' parameter is present in the callback and cryptographically matches the expected issuer pinned to the session state prior to triggering code exchange. The session is invalidated regardless of success or failure. ```typescript import { Request, Response } from 'express'; import crypto from 'node:crypto'; import { exchangeCodeForTokens, getSession, invalidateSession } from './authService'; function constantTimeEquals(a: string, b: string): boolean { const bufA = Buffer.from(a, 'utf-8'); const bufB = Buffer.from(b, 'utf-8'); return bufA.length === bufB.length && crypto.timingSafeEqual(bufA, bufB); } export async function handleOAuthCallback(req: Request, res: Response) { const { code, state, iss } = req.query; if (typeof code !== 'string' || typeof state !== 'string') { return res.status(400).json({ error: 'invalid_request', error_description: 'Missing code or state' }); } const session = await getSession(req, state); if (!session || !constantTimeEquals(session.state, state)) { return res.status(400).json({ error: 'invalid_state', error_description: 'State verification failed' }); } try { // RFC 9207: Authorization Server Issuer Identification Enforcement if (typeof iss !== 'string') { throw new Error('Missing RFC 9207 iss parameter in authorization response'); } const normalizedReceivedIssuer = new URL(iss).origin; const normalizedExpectedIssuer = new URL(session.expectedIssuer).origin; if (!constantTimeEquals(normalizedReceivedIssuer, normalizedExpectedIssuer)) { throw new Error(`Issuer mismatch: expected ${normalizedExpectedIssuer}, received ${normalizedReceivedIssuer}`); } const tokens = await exchangeCodeForTokens({ code, tokenEndpoint: session.tokenEndpoint, clientId: session.clientId, codeVerifier: session.codeVerifier, }); return res.json({ success: true, tokens }); } catch (error) { return res.status(400).json({ error: 'unauthorized_client', error_description: 'Issuer validation failed. Potential mix-up attack detected.' }); } finally { await invalidateSession(session.id); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OAuth 2.1 RFC 9207 Issuer Identification and Multi-IdP Mix-Up Defense

OAuth 2.1 RFC 9207 Issuer Identification and Multi-IdP Mix-Up Defense defines an industrial-grade behavioral standard for security engineering. Enforces strict OAuth 2.1 and RFC 9207 Authorization Server Issuer Identification across federated identity clients to neutralize multi-IdP authorization mix-up attacks. Authorization callback handlers MUST validate that the returned 'iss' parameter identically matches the expected issuer anchored to the initiated transaction state before dispatching code exchange requests. Any response with a missing or mismatched issuer MUST be rejected immediately to prevent credential forwarding to attacker-controlled endpoints. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Exchanging Authorization Codes Without Validating RFC 9207 Issuer Identity Against Session State Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Exchanging Authorization Codes Without Validating RFC 9207 Issuer Identity Against Session State	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS bind the intended Authorization Server's canonical issuer identifier (`issuer`) into the client transaction session state prior to redirecting the user-agent.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.