作为开发者，如果你正在为你的 SaaS 产品添加 2FA 功能，集成 TOTP 是兼容性最佳的选择。用户可以使用谷歌身份验证器电脑端或任何兼容 RFC 6238 标准的工具完成绑定。

一、为什么选择 TOTP

TOTP（基于时间的一次性密码）是 IETF RFC 6238 定义的国际标准，与谷歌身份验证器电脑端、Authy、1Password 等主流工具完全兼容，用户无需安装额外应用即可使用。

二、密钥生成最佳实践

使用加密安全的随机数生成器生成 160 bit 密钥：

import secrets
secret = secrets.token_hex(20)  # 40 个十六进制字符

三、QR Code 生成

使用 otplib 或 pyotp 等成熟库生成 otpauth URI，再转换为二维码：

import pyotp
import qrcode

totp = pyotp.TOTP(secret)
uri = totp.provisioning_uri(
    name="user@example.com",
    issuer_name="MyApp"
)
qrcode.make(uri).save("qr.png")

四、用户绑定流程

  1. 用户开启 2FA，后端生成密钥并保存到数据库（加密）
  2. 前端展示二维码，用户使用谷歌身份验证器电脑端扫码
  3. 用户输入 6 位动态口令完成首次验证
  4. 展示 8-10 个一次性恢复码供用户保存

五、验证 API 设计

POST /api/verify-2fa
{
  "user_id": "123",
  "code": "123456"
}

Response:
{
  "valid": true,
  "window_used": 0
}
安全建议：务必对数据库中保存的密钥进行 AES-256 加密存储，永远不要返回明文密钥给前端；同时启用滑动窗口 ±30 秒应对时钟漂移。

六、应急与恢复机制

提供一次性恢复码是 TOTP 集成的必备组件，建议生成 10 个 8 位恢复码，hash 后存储到数据库，使用时校验后立即作废。