📚 课程目录第4章授权码模式（Authorization Code）

4. 前端发起授权请求实现：构造授权URL、state防CSRF、scope定义与用户跳转体验

4.1 本章概述

授权码（Authorization Code）流程中，前端发起授权请求是整个交互的起点。用户点击“登录/授权”按钮后，前端必须构造一个符合 OAuth2.0 规范的授权请求 URL，携带 client_id、redirect_uri、response_type=code、scope 以及核心安全参数 state，然后引导用户浏览器跳转到授权服务器。

本章聚焦于：

授权 URL 的构造规范与参数含义
state 参数防跨站请求伪造（CSRF）的设计与实现
scope 的粒度定义及其在支付场景下的典型值
用户跳转体验的优化策略（新窗口 / 同页面跳转 / 弹窗处理）
常见错误与调试手段

前置要求：已拥有注册好的 client_id、client_secret 及配置正确的 redirect_uri。若未完成客户端注册，请先阅读第 3 章。

4.2 授权 URL 构造原理

授权请求本质上是一个 GET 请求，参数以查询字符串形式附加在授权端点（Authorization Endpoint）之后。标准结构如下：

GET /authorize?
    response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://your-app.com/callback
    &scope=openid+payment:read+payment:write
    &state=ENCRYPTED_RANDOM_STATE
    &prompt=consent  HTTP/1.1
Host: auth.payment-provider.com

参数	是否必需	说明	支付场景示例
`response_type`	是	固定为 `code`，表示授权码流程	`code`
`client_id`	是	授权服务器颁发的客户端标识	`pay_sdk_client_001`
`redirect_uri`	是	授权码回调地址，必须与注册时完全一致（包含协议、端口、路径）	`https://merchant.com/oauth/callback`
`scope`	推荐	请求的资源访问权限，多个用空格或 `+` 分隔	`openid payment:read payment:write`
`state`	强烈推荐	防 CSRF 攻击的不透明值，需绑定用户会话	Base64 编码的 32 字节随机数
`prompt`	可选	控制授权 UI 行为：`consent` 强制展示确认、`login` 强制登录、`select_account` 允许选择账号	`consent`

重要：生产环境中必须传递 state 参数，且其值不可预测。若授权服务器不支持验证 state，则所有回调都可能受到 CSRF 攻击，攻击者可利用已认证的用户会话完成恶意授权。

4.3 state 参数防 CSRF 实现

跨站请求伪造（CSRF）在 OAuth 2.0 流程中的表现：攻击者诱导用户点击一个合法授权链接，该链接指向受害者的 redirect_uri，但授权码被攻击者窃取。通过 state 参数，前端在发起请求时生成并存储一个随机值，回调时服务器验证该值与存储值一致，从而阻断伪造回调。

4.3.1 生成与存储 state

在前端（浏览器环境）生成加密安全的随机字符串，并存入 sessionStorage（避免跨标签页干扰）或 localStorage：

// 使用 Web Crypto API 生成 32 字节随机数，转为 Base64URL
function generateState() {
    const array = new Uint8Array(32);
    crypto.getRandomValues(array);
    // 转换为 Base64URL（无填充）
    return btoa(String.fromCharCode(...array))
        .replace(/\+/g, '-')
        .replace(/\//g, '_')
        .replace(/=+$/, '');
}

// 存储到 sessionStorage
function saveState(state) {
    // 为防止 XSS 窃取，可加一层 HMAC 签名，但简化实现如下
    sessionStorage.setItem('oauth_state', state);
}

4.3.2 构造完整授权 URL 并跳转

function buildAuthorizationUrl() {
    const state = generateState();
    saveState(state);

    const params = new URLSearchParams({
        response_type: 'code',
        client_id: 'pay_sdk_client_001',
        redirect_uri: 'https://merchant.com/oauth/callback',
        scope: 'openid payment:read payment:write',
        state: state,
        prompt: 'consent'   // 始终要求用户确认授权
    });
    // 授权端点 URL，从配置读取
    const authEndpoint = 'https://auth.payment-provider.com/authorize';
    return `${authEndpoint}?${params.toString()}`;
}

// 用户点击按钮时执行
function initiateOAuth() {
    const url = buildAuthorizationUrl();
    // 同页面跳转（推荐）
    window.location.href = url;
}

4.3.3 回调时验证 state

当授权服务器将用户重定向回 redirect_uri 时，前端或后端需从查询参数中取出 state，并与之前存储的值比对：

// 在回调页面（/callback）中执行
function verifyState() {
    const urlParams = new URLSearchParams(window.location.search);
    const returnedState = urlParams.get('state');
    const savedState = sessionStorage.getItem('oauth_state');

    if (!returnedState || returnedState !== savedState) {
        console.error('[CSRF] state mismatch or missing');
        // 中止流程，显示错误页面
        return false;
    }
    // 验证通过后清除存储
    sessionStorage.removeItem('oauth_state');
    return true;
}

  安全增强：部分支付 SDK 要求 state 必须 绑定当前用户会话 ID（如加上 sessionId 的 HMAC），以防止攻击者在同一浏览器中伪造不同用户的 state。此方案称为“会话绑定 state”。

4.4 scope 定义与支付场景最佳实践

scope 是授权范围的字符串集合。在支付 SDK 场景中，通常按“读/写”和“资源类型”划分。以下是一个支付平台典型 scope 定义：

scope	权限	说明
`openid`	读取用户身份标识	用于识别支付账户（非敏感信息）
`payment:read`	查询交易记录、余额	对账单、历史订单查询
`payment:write`	发起支付、取消支付	核心支付操作，需用户明确同意
`refund:write`	发起退款	高敏操作，通常需要额外验证
`payment:recurring`	创建定期扣款计划	订阅支付场景专用

构造授权 URL 时，scope 参数应使用 空格分隔（URL 中编码为 + 或 %20）：

scope=openid payment:read payment:write

授权服务器收到后会展示权限确认页面，用户可按需勾选。若请求了未在客户端注册中授权的 scope，会直接返回错误 invalid_scope。

4.5 用户跳转体验优化

授权请求以浏览器重定向方式执行。常见实现方式及优缺点：

方式	实现	优点	缺点
同页面跳转	`window.location.href = url`	简单、保持浏览历史	页面刷新，用户失去当前操作上下文
新窗口/新标签页	`window.open(url, '_blank')`	保留原页面，用户授权后可关闭窗口	可能被浏览器拦截弹出窗口；无法保证窗口关闭时自动回调
iframe 嵌入	不适合授权流程（跨域限制）	——	违反安全策略，不推荐
重定向 + 深链接（移动端）	scheme 或 universal link	原生 App 体验	需配置 App Links / URI scheme

推荐方案：桌面端使用同页面跳转，移动端配合 window.location.href 同时监听 visibilitychange 事件以检测用户是否从授权服务器返回。此外，应在跳转前保存应用状态（如当前页面 URL），以便回调后恢复。

// 保存跳转前状态
sessionStorage.setItem('oauth_before_url', window.location.href);
// 然后执行跳转
window.location.href = authorizationUrl;

UX 技巧：在跳转授权服务器之前，显示一个短暂的“正在跳转到支付授权页面…”加载提示（而非白屏），可改善感知等待时间。使用 <div id="loading-overlay"> 并在跳转后立即隐藏。

4.6 调试与常见错误

错误现象	可能原因	排查方法
授权服务器返回 `invalid_request`	缺少必需参数（如 `response_type`）	检查 URL 构造，使用开发者工具查看网络请求
回调中 `error=access_denied`	用户拒绝了授权	不要重试，提示用户需手动同意
回调中无 `state` 参数	授权服务器不支持回传 state	升级授权服务器或使用 PKCE 代替（第 6 章详解）
`invalid_scope`	scope 包含了未注册的范围	检查客户端注册时声明的 scope 列表，去除未授权项
回调页面收到 `state` 但本地无存储值	sessionStorage 被清空（如用户复制链接在新标签页打开）	改用 localStorage 或通过后端验证 state

调试时可以在授权 URL 后添加 &test=true（需授权服务器支持调试模式），或使用沙箱环境（sandbox）避免干扰真实用户。

4.7 实现流程总览

下图展示了前端发起授权请求时的完整流程，从用户点击到浏览器跳转至授权服务器：

4.8 性能与稳定性优化

异步生成 state：在用户点击按钮前，利用空闲时间预生成 state 并缓存，减少点击到跳转的延迟。但需注意 sessionStorage 的读写时机。
防止重复跳转：在 initiateOAuth() 中加入标志位 isRedirecting，避免用户多次点击造成多个授权请求。
错误回退：若 crypto.getRandomValues() 不可用（如旧浏览器），可降级为 Math.random() 结合 Date.now() 和随机哈希，但仍需后端再次验证。
重定向超时：如果授权服务器长时间无响应，应提供“重试”或“联系客服”选项。

注意：切勿在浏览器端硬编码 client_secret 或任何敏感凭证。前端构造授权 URL 只使用 client_id，client_secret 仅在后端使用。

4.9 本章小结

本章详细讲解了前端发起 OAuth 2.0 授权请求时的关键实现步骤，包括：

授权 URL 的必备参数与排序规范；
state 参数的生成、存储与回调验证，从根本上防御 CSRF 攻击；
支付场景中 scope 的典型划分与使用注意事项；
用户跳转体验的三种方式对比及推荐实践；
常见错误排查表与性能优化要点。