高级认证模式 — OAuth 2.0、JWT、密钥轮换

认证概述

Smart Money API支持多种认证方法，旨在适应不同的应用架构、安全需求和组织策略。理解这些模式可确保您的集成既安全又高效。

Smart Money API的认证操作分为三个主要层面：

• API密钥 — 适用于开发和简单集成的简单bearer令牌认证
• JWT令牌 — 用于分布式系统和微服务的无状态加密签名令牌
• OAuth 2.0 — 适用于第三方集成和SaaS应用的委托授权框架

每种方法都有独特优势。API密钥最适合后端到后端通信且凭证存储受控的场景。JWT令牌在无共享状态的分布式架构中表现优异。OAuth 2.0为第三方应用提供用户委托访问权限。

API密钥认证

API密钥是最简单的认证机制——它们是专为您的账户生成的随机字符串，用于向Smart Money API标识您的应用程序。每个请求都必须在请求头或查询参数中包含您的API密钥。

基于请求头的API密钥

推荐的方式是使用Bearer方案在Authorization请求头中传递API密钥：

查询参数形式的API密钥

对于WebSocket连接或无法修改请求头的情况，可将API密钥作为查询参数传递：

API密钥特性

API密钥安全实践

• 环境变量 ——将密钥存储在.env文件中（不要提交到版本控制系统），并在运行时加载
• 保险库系统 — 生产环境中使用 HashiCorp Vault、AWS Secrets Manager 或 Azure Key Vault
• 分离密钥 — 区分测试密钥和正式密钥；定期轮换测试密钥
• 最小权限原则 — 尽可能为不同集成创建独立密钥
• 审计日志 — 记录所有API密钥创建和使用事件

Bearer Token模式

Bearer令牌通过添加上下文、有效期和刷新机制扩展了基础API密钥概念，适合需要程序化凭证管理的应用场景。

获取Bearer令牌

用API密钥和密钥兑换24小时有效的Bearer令牌：

令牌响应格式

该端点返回带有元数据的Bearer令牌：

使用Bearer令牌

在所有后续请求的Authorization头中包含令牌：

令牌刷新流程

当令牌临近过期时，使用刷新令牌获取新令牌（无需提供API密钥）：

OAuth 2.0实现方案

OAuth 2.0允许用户授权应用访问其Smart Money API账户而无需共享凭证，这对SaaS平台、第三方集成和多租户应用至关重要。

OAuth 2.0授权码流程

Web应用的标准流程：

1. 用户发起登录 — 用户点击"连接Smart Money API"
2. 跳转至授权服务器 — 您的应用将用户重定向至Smart Money授权端点
3. 用户授权 — 用户查看请求的权限范围并授权访问
4. 返回授权码 — 用户被重定向回应用并携带授权码
5. 兑换令牌 — 后端用授权码兑换访问令牌（前端不接触授权码）
6. 存储令牌 — 安全存储刷新令牌；使用访问令牌进行API调用

步骤1：将用户重定向至授权端点

步骤2：处理回调并交换代码

OAuth授权范围

仅请求应用所需的权限范围。Smart Money API定义了以下范围：

JWT令牌管理

JWT（JSON Web令牌）提供无状态认证——服务器无需存储会话数据。Smart Money API采用RS256（RSA SHA-256签名）进行令牌签名，无需联系API即可验证。

JWT结构

JWT令牌由三部分组成，以点号分隔：

JWT头部

头部标识算法与令牌类型：

JWT载荷声明

载荷包含声明（关于用户/应用的陈述）：

验证JWT签名

下载Smart Money的公钥并在接受令牌前验证：

密钥轮换策略

定期密钥轮换对维护安全至关重要。即使安全措施完善，也应假设密钥可能泄露并实施系统化轮换。

轮换频率

Smart Money根据密钥类型和使用场景推荐不同轮换周期：

零停机轮换流程

在不中断服务的情况下轮换密钥：

1. 生成新密钥 — 通过仪表板或API创建新API密钥
2. 部署新密钥 — 在测试环境更新应用密钥，充分测试
3. 渐进式发布 — 部署至10%的服务器，监控错误
4. 全面上线 — 部署至剩余服务器
5. 验证流量 — 确认所有请求使用新密钥
6. 停用旧密钥 — 将旧密钥标记为无效但不立即删除
7. 删除旧密钥 — 48小时内无错误则永久删除

紧急密钥轮换

若怀疑密钥泄露：

Kubernetes自动化轮换

使用Kubernetes Secrets和Operator实现自动轮换：

多因素认证(MFA)

对访问生产数据的账户，MFA通过要求除凭证外的第二验证因素提供额外安全层。

支持的MFA方式

• TOTP(基于时间的一次性密码) — 如Google Authenticator、Authy等应用
• WebAuthn/FIDO2 — 硬件安全密钥、生物识别
• 短信验证码 — 安全性较低但普遍支持
• 邮件确认 — 发送验证码至注册邮箱

为账户启用TOTP

API操作中的MFA

部分操作即使认证后仍需MFA确认：

安全最佳实践

认证强度取决于实施方式。遵循以下实践以保持安全：

密钥管理

• 切勿将密钥提交至版本控制 — 使用.gitignore的.env文件
• 使用环境变量 — 从安全密钥管理系统加载
• 扫描代码库 — 使用TruffleHog等工具检测暴露的密钥
• 审计访问日志 — 监控密钥访问者及时间

传输安全

• 始终使用HTTPS — 切勿通过未加密连接发送凭证
• 验证SSL证书 — 生产环境勿禁用证书验证
• 使用证书锁定 — 移动端应用防止中间人攻击
• 强制TLS 1.2+ — 禁用旧版协议

凭证处理

• 哈希加密密钥 — 存储bcrypt或Argon2哈希值，禁用明文
• 最小化存活时间 — 仅在内存中临时保留凭证
• 清除敏感数据 — 使用后显式覆写凭证
• 使用安全库 — 勿自行实现加密算法

日志与监控

• 禁止记录凭证 — 日志中脱敏密钥，使用日志掩码
• 记录认证事件 — 追踪成功/失败的登录尝试
• 监控异常行为 — 对异常访问模式发出警报
• 审计密钥使用 — 追踪密钥访问的数据范围

企业级认证方案

大型组织通常需要额外安全控制和合规能力。

SAML 2.0集成

面向企业客户，Smart Money API支持与组织身份提供商(Okta、Azure AD等)的SAML 2.0集成：

• 单点登录(SSO) — 用户通过企业IdP认证
• 自动配置 — 基于群组成员创建/禁用账户
• 强制措施 — 要求所有用户通过SAML访问

IP白名单

限制API访问权限至特定IP地址或CIDR范围：

审计日志与合规

企业版套餐包含全面的合规审计日志：

身份验证问题排查

无效API密钥错误

问题： 收到"401 Unauthorized - Invalid API Key"

解决方案：

• 验证密钥格式（应以sk_test_或sk_live_开头）
• 检查密钥首尾是否有空格
• 确认密钥未被停用或轮换
• 验证是否使用正确环境（测试环境用测试密钥，生产环境用正式密钥）
• 检查API密钥权限是否符合端点要求

令牌过期错误

问题： Bearer令牌过期，请求失败

解决方案：

• 使用刷新令牌获取新访问令牌
• 在过期前5分钟实施自动令牌刷新
• 安全存储刷新令牌（SPA应用勿存于localStorage）
• 通过尝试刷新令牌流程处理401响应

CORS/预检请求错误

问题： 浏览器因CORS错误阻止请求

解决方案：

• 浏览器发起的API调用必须来自白名单域名
• 通过仪表盘添加域名：设置→CORS来源
• 浏览器会自动发送OPTIONS预检请求
• 开发环境可使用localhost:3000等地址

MFA验证未完成

问题： 即使输入正确验证码，MFA操作仍失败

解决方案：

• 确保服务器时间同步（TOTP依赖时间验证）
• 验证码仅30秒有效，请生成新码
• 验证器应用不可用时使用备用码
• 可通过注册邮箱进行账户恢复