RFC 8693 Token Exchange: Mandatory Audience Downscoping & Actor Verification

--- description: RFC 8693 Token Exchange: Mandatory Audience Downscoping & Actor Verification - Enforces deterministic token downscoping and explicit actor verification via RFC 8693 OAuth 2.0 Token Exchange during east-west service calls. Prevents cross-service privilege escalation, delegation pivot vulnerabilities, and ambient credential pass-through by restricting audience scope and anchoring delegation chains. globs: src/auth/**/*.ts, src/clients/**/*.ts, src/middleware/**/*.ts, src/services/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rfc-8693-token-exchange-audience-downscoping" --- # RFC 8693 Token Exchange: Mandatory Audience Downscoping & Actor Verification > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Raw Token Pass-Through and Broad Audience Propagation in East-West Service Delegation ## System Constraints You are a Principal Security Architect enforcing RFC 8693 OAuth 2.0 Token Exchange for all east-west microservice interactions. You must block raw bearer token forwarding, require single-target audience downscoping, enforce minimal required scopes, and ensure downstream validation of nested actor ('act') claims. ## Strict Guidelines - Engineers MUST NEVER forward an incoming North-South bearer token verbatim to an east-west internal service. - Services MUST execute an RFC 8693 Token Exchange (grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange') against the IdP/STS before initiating an internal RPC/HTTP request. - Token exchange requests MUST set 'subject_token' to the validated inbound token, 'subject_token_type' to 'urn:ietf:params:oauth:token-type:access_token', and provide explicit singular 'audience' downscoping. - Exchanged tokens MUST contain a nested actor ('act') claim verifying the intermediate service identity (caller identity) acting on behalf of the subject. - Downstream services MUST explicitly validate that their exact service identifier is the sole recipient in the 'aud' claim and reject tokens with wildcards or missing 'act' claims when delegation is active. - Services MUST request the minimal necessary 'scope' subset during the exchange, never mirroring all inbound scopes unconditionally. ## Bad vs Good Implementations ### East-West Microservice Delegation with RFC 8693 Token Exchange #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Raw bearer tokens forwarded across service boundaries expose upstream tokens to downstream services. If the downstream service is compromised, it can replay the broad-scoped token against other unrelated services. ```typescript import axios from 'axios'; import { Request, Response } from 'express'; export async function handleOrderDispatch(req: Request, res: Response) { const userToken = req.headers.authorization; // CRITICAL ANTI-PATTERN: Verbatim North-South token pass-through. // Shipping service receives a token scoped for OrderService or wildcard audience. // If ShippingService is compromised, it can replay userToken to Billing or other services. const shippingResponse = await axios.post( 'https://shipping-service.internal/api/shipments', { orderId: req.body.orderId }, { headers: { Authorization: userToken, // Confused Deputy & Cross-service Privilege Escalation }, } ); return res.status(200).json(shippingResponse.data); } ``` #### Production Standard (Correct) > **Standard**: The service exchanges the inbound token for a short-lived token targeted strictly to 'urn:service:shipping' with the minimal 'shipments:create' scope, recording an actor ('act') claim that preserves verifiable delegation provenance. ```typescript import axios from 'axios'; import { Request, Response } from 'express'; import { exchangeToken } from '../auth/tokenExchangeClient'; const SHIPPING_SERVICE_AUDIENCE = 'urn:service:shipping'; const SHIPPING_MINIMAL_SCOPE = 'shipments:create'; export async function handleOrderDispatch(req: Request, res: Response) { const authHeader = req.headers.authorization; if (!authHeader?.startsWith('Bearer ')) { return res.status(401).json({ error: 'Missing bearer token' }); } const rawSubjectToken = authHeader.substring(7); // RFC 8693 Downscoped Token Exchange const downscopedToken = await exchangeToken({ subjectToken: rawSubjectToken, subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token', audience: SHIPPING_SERVICE_AUDIENCE, scope: SHIPPING_MINIMAL_SCOPE, }); const shippingResponse = await axios.post( 'https://shipping-service.internal/api/shipments', { orderId: req.body.orderId }, { headers: { Authorization: `Bearer ${downscopedToken}`, }, } ); return res.status(200).json(shippingResponse.data); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: RFC 8693 Token Exchange: Mandatory Audience Downscoping & Actor Verification

RFC 8693 Token Exchange: Mandatory Audience Downscoping & Actor Verification defines an industrial-grade behavioral standard for security engineering. Enforces deterministic token downscoping and explicit actor verification via RFC 8693 OAuth 2.0 Token Exchange during east-west service calls. Prevents cross-service privilege escalation, delegation pivot vulnerabilities, and ambient credential pass-through by restricting audience scope and anchoring delegation chains. 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: Raw Token Pass-Through and Broad Audience Propagation in East-West Service Delegation 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	Raw Token Pass-Through and Broad Audience Propagation in East-West Service Delegation	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 NEVER forward an incoming North-South bearer token verbatim to an east-west internal service.

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.