3. 支付平台应用注册与凭证配置：Client ID、Client Secret、签名算法、回调URL白名单
3.1 原理概述
OAuth2.0 授权流程的第一步是服务提供方（支付平台）为第三方应用颁发唯一的身份凭证。这些凭证用于在后续的授权请求、令牌交换和资源访问中标识并验证应用的合法性。核心要素包括：
- Client ID：应用的公开标识，在授权请求中传递，用于让授权服务器识别请求来源。
- Client Secret：应用的私密密钥，用于签名请求或进行客户端认证（尤其是 authorization_code 和 client_credentials 模式）。
- 签名算法：支付平台要求使用特定算法（如 HMAC-SHA256、RSA-SHA256）对请求参数进行签名，确保数据完整性和防篡改。
- 回调URL白名单：预先注册的合法的重定向 URI，授权服务器在颁发授权码或令牌时只允许回调到白名单内的地址，防止开放重定向攻击。
安全原则：Client Secret 必须安全存储在服务端，绝不能暴露在客户端代码（如浏览器、移动App）中。支付平台的凭证配置入口通常位于“开发者中心”或“应用管理”页面。
3.2 实现流程
- 注册应用：登录支付开放平台，创建一个新的应用（如“商户收款应用”），填写应用名称、描述、所属商户号等信息。
- 获取凭证：平台自动生成 Client ID 和 Client Secret。部分平台允许重置 Secret。
- 配置回调URI：添加系统回调地址（如
https://yourdomain.com/oauth/callback）。支付平台通常支持多个 URI，且要求使用 HTTPS。 - 选择签名算法：在应用详情中指定签名算法（如 HMAC-SHA256），或根据平台要求使用默认算法。
- 下载/复制凭证：保存 Client Secret（部分平台只显示一次，需自行妥善保管）。
实操建议：在生产环境上线前，先在沙箱/测试环境中完成注册和凭证配置，避免因回调URL错误导致授权失败。
3.3 核心配置项详解
| 参数 | 示例值 | 说明 |
|---|---|---|
| Client ID | wx_app_20250301a1b2 |
全局唯一，长度32-64字符，包含字母数字下划线。 |
| Client Secret | sk_live_9f8e7d6c5b4a3210 |
高度敏感，长度至少32字符，包含大小写字母与数字。 |
| 签名算法 | HMAC-SHA256 |
支付平台常用 HMAC-SHA256 或 RSA-SHA256，需与文档一致。 |
| 回调URL | https://api.example.com/oauth/cb |
白名单模式，最多可添加5个，必须使用 HTTPS 协议。 |
| 应用状态 | enabled |
上线前需手动启用，否则授权服务器会拒绝请求。 |
3.4 签名算法与示例
支付平台通常要求对授权请求参数按字典序排序，拼接成字符串，再用 Client Secret 作为密钥计算签名。以 HMAC-SHA256 为例：
StringToSign = "app_id=wx_app_20250301a1b2×tamp=1711800000&nonce_str=K3H5mQ9v"
Signature = hmac_sha256(StringToSign, ClientSecret)
// 输出：A1B2C3D4E5F6ABCDEF1234567890abcdef在 OAuth2.0 授权码模式中，签名可用于 client_secret_basic（HTTP Basic Auth 传递 Client ID:Secret）或 client_secret_post（POST 体携带 Secret）。
3.5 回调URL白名单校验规则
- 精确匹配：回调 URL 必须完全等于白名单中某个 URI（包括路径、端口、协议）。
- 通配符：部分支付平台支持路径通配符（如
https://*.example.com/oauth/callback），但安全等级较低。 - 端口敏感：若白名单中未指定端口，则只允许默认端口（443）。
- 子路径限制：不允许“前缀匹配”，例如
https://example.com/oauth不能通过https://example.com/oauth/evil。
常见错误：回调URL末尾多了斜杠（
/）导致匹配失败。建议在平台配置时去尾斜杠，并在应用代码中也保持一致。
3.6 结构图：应用凭证与回调关系
3.7 调试与验证
- 检查凭证有效性：使用 Payment SDK 提供的校验工具（如
validate_credentials）测试 Client ID 和 Secret 是否能通过认证。 - 测试回调URL：在浏览器中手动访问回调 URL，确认服务器正常响应 200，且没有跳转到其他页面。
- 签名校验：在开发阶段，开启支付平台的“签名校验日志”，对比本地签名与平台接收到的签名是否一致。
- 沙箱环境：支付平台通常提供测试凭证（Client ID 以
sandbox_开头），在沙箱中完成调试后再切换生产凭证。
3.8 部署与生产配置
- 使用环境变量：将 Client Secret 配置为服务器环境变量，如
PAY_CLIENT_SECRET，避免硬编码。 - 启用HTTPS：确保生产环境的回调 URL 使用 HTTPS 并拥有有效证书。
- 配置白名单：只添加必要的回调 URI，定期审计白名单并移除不再使用的地址。
- 监控凭据变更：支付平台支持凭据撤回与重置，生产环境应配合运维流程及时更新配置并重启服务。
3.9 常见错误与解决方案
| 错误码 | 现象 | 可能原因 | 解决措施 |
|---|---|---|---|
invalid_client |
授权请求被拒，提示“client_id无效” | Client ID 拼写错误或应用状态为禁用 | 核对平台上的 Client ID，启用应用状态 |
invalid_redirect_uri |
回调后出现 400 错误 | 回调 URL 不在白名单中 | 检查白名单配置，包括协议、端口、路径完全匹配 |
invalid_signature |
签名校验失败日志 | 签名算法不一致或 Secret 错误 | 确认算法类型（如 HMAC-SHA256），重新生成签名并比对原始字符串 |
3.10 性能与稳定性优化
- 缓存凭证：在服务端内存中缓存 Client ID 与 Secret，减少每次请求时的数据库读取。
- 签名预计算：对于固定参数（如商户号）的请求，可预计算签名模板，仅在时间戳和随机数变化时重新生成。
- 回调URL限流：在回调端点实施请求频率限制（如每 IP 每分钟100次），防止异常重放或扫描。
- Watchdog 监控：配置对支付平台凭证可用性的健康检查，当返回
invalid_client时触发报警并自动切换备用应用。
生产经验：建议为每个环境（开发、测试、生产）创建独立的应用凭证，并利用 CI/CD 工具自动注入环境变量，避免人工误操作。