737 lines
25 KiB
Markdown
737 lines
25 KiB
Markdown
---
|
||
tags:
|
||
- OAuth2
|
||
- MFA
|
||
- Authentication
|
||
- Authorization
|
||
- Security
|
||
- TOTP
|
||
- OpenID-Connect
|
||
- 2FA
|
||
create time: 2026-05-17 20:00
|
||
---
|
||
|
||
# OAuth2 + MFA
|
||
|
||
## 概述
|
||
|
||
本文档系统梳理 **OAuth 2.0**（授权框架）与 **多因素认证（MFA）** 的核心原理、设计模式和工程实践。涵盖 OAuth2 的四种授权流程、MFA 的多因素分类、两者在真实系统中的集成方式（包括 MFA-challenged 场景），以及 Go 后端和 React/TypeScript 前端的完整示例。旨在让读者能够从零搭建一个支持 MFA 的企业级认证体系。
|
||
|
||
> [!question] 思考题
|
||
> OAuth2 本质上是**授权协议**而非认证协议。那为什么业界常用它来做登录？又如何在 OAuth2 之上叠加 MFA 能力？带着这两个问题开始阅读。
|
||
|
||
---
|
||
|
||
## 一、OAuth2 核心概念
|
||
|
||
### 1.1 四个角色
|
||
|
||
```mermaid
|
||
graph LR
|
||
A["用户 (Resource Owner)"] -->|"授予权限"| B["客户端 (Client)"]
|
||
B -->|"请求令牌"| C["授权服务器 (AS)"]
|
||
C -->|"发放 Access Token"| B
|
||
B -->|"携带 Token"| D["资源服务器 (RS)"]
|
||
D -->|"返回受保护资源"| B
|
||
style A fill:#e1f5fe
|
||
style B fill:#fff3e0
|
||
style C fill:#e8f5e9
|
||
style D fill:#fce4ec
|
||
```
|
||
|
||
| 角色 | 职责 | 常见身份 |
|
||
|------|------|---------|
|
||
| Resource Owner | 资源拥有者 | 终端用户 |
|
||
| Client | 发起请求的应用 | Web App / Mobile App / SPA |
|
||
| Authorization Server | 验证用户并发放令牌 | Keycloak / Auth0 / 自研 |
|
||
| Resource Server | 托管受保护资源的 API | 后端微服务 |
|
||
|
||
> [!tip] 关键认知
|
||
> 很多系统中 AS 和 RS 部署在同一域名下（如 `auth.example.com` 和 `api.example.com`），对外表现为一个统一平台。但它们在架构上是解耦的。
|
||
|
||
### 1.2 四种授权流程（Grant Types）
|
||
|
||
| Grant Type | 适用场景 | 安全性 |
|
||
|-----------|---------|-------|
|
||
| **Authorization Code** | 服务端渲染的后端应用（SPA + Backend） | ★★★★★ |
|
||
| **Authorization Code + PKCE** | SPA、移动端等无法保密 Client Secret 的场景 | ★★★★★ |
|
||
| **Implicit Flow** | ~~已废弃~~ 不推荐使用 | ★★★ |
|
||
| **Client Credentials** | 机器对机器通信（Service-to-Service） | ★★★★☆ |
|
||
| **Device Code** | 无浏览器设备（IoT、电视） | ★★★★ |
|
||
|
||
#### Authorization Code + PKCE（推荐方案）
|
||
|
||
这是当前最佳实践，尤其适合前后端分离架构：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant C as Client(SPA)
|
||
participant AS as Auth Server
|
||
participant RS as Resource Server
|
||
|
||
U->>C: 1. 点击"登录"
|
||
C->>C: 2. 生成 code_verifier & code_challenge
|
||
C->>AS: 3. 重定向到 /authorize?code_challenge=S256
|
||
AS->>U: 4. 展示登录页 + MFA 提示
|
||
U->>AS: 5. 输入密码 + TOTP 验证码
|
||
AS->>C: 6. 回调 /callback?code=AUTH_CODE
|
||
C->>AS: 7. 用 code + code_verifier 换 token
|
||
AS->>C: 8. 返回 {access_token, refresh_token, id_token}
|
||
C->>RS: 9. 携带 access_token 请求 API
|
||
RS->>RS: 10. 验证签名并返回资源
|
||
```
|
||
|
||
> [!question] 为什么需要 PKCE？
|
||
> 传统的 Authorization Code 要求客户端持有 `client_secret`。但对于浏览器端或移动端的 SPA 应用，Secret 必然暴露在前端代码中——任何拦截都能窃取。PKCE 通过每次请求动态生成 `code_challenge`（基于 `code_verifier`），确保只有发起请求的客户端能用该 authorization code 换取 token，即使 code 被截获也无法利用。
|
||
|
||
### 1.3 Token 类型
|
||
|
||
```typescript
|
||
// Access Token — 短期有效，用于访问 API
|
||
interface AccessToken {
|
||
sub: string; // 用户唯一标识
|
||
iss: string; // 签发者
|
||
aud: string[]; // 目标受众（资源服务器）
|
||
exp: number; // 过期时间（通常 15min ~ 1hr）
|
||
iat: number; // 签发时间
|
||
scopes: string[]; // 授权范围
|
||
mfa_verified?: boolean; // MFA 是否已验证
|
||
session_id: string; // 关联会话
|
||
}
|
||
|
||
// Refresh Token — 长期有效，用于获取新的 Access Token
|
||
// ⚠️ 绝对不应该出现在前端浏览器中
|
||
interface RefreshToken {
|
||
sub: string;
|
||
jti: string; // Token ID（用于吊销）
|
||
exp: number; // 过期时间（通常 7 ~ 30 days）
|
||
device_fingerprint?: string;
|
||
}
|
||
```
|
||
|
||
> [!warning] 安全陷阱
|
||
> Access Token 存 `localStorage` 还是 `memory`？答案：**永远放内存**。`localStorage` 和 `sessionStorage` 可被任意 JavaScript 读取，是 XSS 攻击的天然蜜罐。HTTP-only Cookie 适合后端渲染，但不适用于纯 SPA。
|
||
|
||
---
|
||
|
||
## 二、多因素认证（MFA）基础
|
||
|
||
### 2.1 三大因素分类
|
||
|
||
```mermaid
|
||
quadrantChart
|
||
title "MFA 因素对比"
|
||
x-axis "低用户体验" --> "高用户体验"
|
||
y-axis "技术成熟度高" --> "技术成熟度低"
|
||
"短信验证码": [0.4, 0.6]
|
||
"邮箱验证码": [0.5, 0.75]
|
||
"TOTP (Google Authenticator)": [0.75, 0.9]
|
||
"生物识别 (指纹/人脸)": [0.85, 0.85]
|
||
"硬件密钥 (YubiKey)": [0.6, 0.7]
|
||
"Push Notification": [0.9, 0.8]
|
||
```
|
||
|
||
| 因素 | 例子 | 优势 | 劣势 |
|
||
|------|------|------|------|
|
||
| **Knowledge**（所知） | 密码、PIN | 零成本，用户熟悉 | SIM 卡劫持、钓鱼可绕过 |
|
||
| **Possession**（所有） | 手机 app、硬件密钥 | 独立于密码 | 依赖设备可用性 |
|
||
| **Inherence**（所是） | 指纹、面部识别 | 无缝体验 | 隐私争议、误识率 |
|
||
|
||
### 2.2 TOTP 算法详解（RFC 6238）
|
||
|
||
TOTP（Time-based One-Time Password）是目前最常用的 Possession 因素实现。
|
||
|
||
#### TOTP 算法流程
|
||
|
||
```
|
||
输入：共享密钥 K + 当前时间 T
|
||
输出：6~8 位数字验证码
|
||
|
||
步骤:
|
||
1. T = floor(当前 Unix Timestamp / 30) // 每 30 秒一个窗口
|
||
2. Counter = big-endian byte representation of T
|
||
3. HMAC-SHA256(K, Counter) → 20 字节结果
|
||
4. Dynamic Truncation → 提取 4 字节
|
||
5. Modulo 10^digits → 6 或 8 位数字
|
||
```
|
||
|
||
> [!example] 为什么是 30 秒？
|
||
> 30 秒是安全窗口和安全性的折衷——太短用户来不及操作，太长增加了被盗用的风险。配合 ±1 个窗口的漂移容忍（允许前后两个值），实际容错范围是 90 秒。
|
||
|
||
#### Go 实现 TOTP 验证
|
||
|
||
```go
|
||
package totp
|
||
|
||
import (
|
||
"crypto/hmac"
|
||
"crypto/sha256"
|
||
"encoding/binary"
|
||
"fmt"
|
||
"math"
|
||
"time"
|
||
)
|
||
|
||
// Verify 校验 TOTP 码，tolerance 表示允许的时间窗口偏移量
|
||
func Verify(secret, code string, digits int, tolerance int, now time.Time) bool {
|
||
window := now.Unix() / 30
|
||
|
||
for offset := -tolerance; offset <= tolerance; offset++ {
|
||
if verifyAtWindow(secret, code, int(window+offset), digits) {
|
||
return true
|
||
}
|
||
}
|
||
return false
|
||
}
|
||
|
||
func verifyAtWindow(secret, code string, window, digits int) bool {
|
||
mac := hmac.New(sha256.New, []byte(secret))
|
||
buf := make([]byte, 8)
|
||
binary.BigEndian.PutUint64(buf, uint64(window))
|
||
mac.Write(buf)
|
||
hash := mac.Sum(nil)
|
||
|
||
offset := hash[len(hash)-1] & 0x0F
|
||
codeBytes := binary.BigEndian.Uint32(hash[offset : offset+4]) & 0x7FFFFFFF
|
||
computed := int(codeBytes) % int(math.Pow10(digits))
|
||
expected := fmt.Sprintf("%06d", computed)
|
||
|
||
// constant-time comparison, 防止 timing attack
|
||
return hmac.Equal([]byte(expected), []byte(code))
|
||
}
|
||
```
|
||
|
||
> [!note] 关键点解释
|
||
> - `secret` 是服务器与客户端共享的基础密钥（Base32 编码），通过 QR 码首次绑定
|
||
> - `tolerance=1` 是最常用的配置，提供 ±30s 的容差
|
||
> - 比较时使用 `hmac.Equal` 进行 constant-time comparison，防止 timing attack
|
||
|
||
### 2.3 WebAuthn / FIDO2（下一代 MFA）
|
||
|
||
WebAuthn 由 W3C 定义，取代传统 TOTP，将"possessing a device"变为"possessing a cryptographic key bound to a domain"。
|
||
|
||
```
|
||
流程:
|
||
注册:
|
||
1. 客户端请求凭证创建 → 服务端生成 challenge
|
||
2. 浏览器调用 navigator.credentials.create()
|
||
3. 用户通过生物识别/PIN 授权
|
||
4. 硬件安全模块（TPM/Safe Area）生成公私钥对
|
||
5. 公钥 + attestation 返回服务端，服务端持久化
|
||
|
||
认证:
|
||
1. 登录时服务端发送 challenge
|
||
2. 浏览器调用 navigator.credentials.get()
|
||
3. 硬件验证身份后使用私钥签名
|
||
4. 服务端用已存储的公钥验证签名
|
||
```
|
||
|
||
> [!tip] 为什么 WebAuthn 比 TOTP 更安全？
|
||
> - **抗钓鱼**：密钥绑定特定 origin，攻击者无法诱骗用户使用其网站的密钥
|
||
> - **私钥不出设备**：私钥永远不会离开安全硬件
|
||
> - **无需共享密钥**：消除了二维码泄露导致的全局风险
|
||
|
||
---
|
||
|
||
## 三、OAuth2 + MFA 的深度集成
|
||
|
||
### 3.1 MFA-Challenged 模式
|
||
|
||
这是企业级认证中最关键的集成点。当用户认证成功但尚未完成 MFA 验证时，授权服务器应返回 `mfa_required` 错误，而非直接发放 token。
|
||
|
||
```
|
||
┌───────────── 第一次请求 ─────────────┐
|
||
│ Client → /authorize │
|
||
│ 用户输入用户名 + 密码 │
|
||
│ ✅ 密码正确 │
|
||
│ ❓ MFA 状态？ │
|
||
│ → 需要 MFA │
|
||
│ │
|
||
│ Client ← { │
|
||
│ "error": "mfa_required", │
|
||
│ "challenge_id": "uuid-xxxx", │
|
||
│ "supported_factors": ["totp","webauthn"] │
|
||
│ } │
|
||
└──────────────────────────────────────┘
|
||
|
||
┌───────────── 第二次请求（补充 MFA）───┐
|
||
│ Client → /token │
|
||
│ headers: │
|
||
│ X-MFA-Challenge-ID: uuid-xxxx │
|
||
│ X-MFA-Factor: totp │
|
||
│ body: │
|
||
│ mfa_code: "123456" │
|
||
│ │
|
||
│ ✅ MFA 验证成功 │
|
||
│ │
|
||
│ Client ← { │
|
||
│ "access_token": "xxx", │
|
||
│ "refresh_token": "yyy", │
|
||
│ "mfa_verified": true │
|
||
│ } │
|
||
└───────────────────────────────────────┘
|
||
```
|
||
|
||
#### Go 后端处理 MFA Challenge
|
||
|
||
```go
|
||
package auth
|
||
|
||
import (
|
||
"context"
|
||
"encoding/json"
|
||
"fmt"
|
||
"net/http"
|
||
"time"
|
||
|
||
"github.com/google/uuid"
|
||
"github.com/redis/go-redis/v9"
|
||
)
|
||
|
||
type AuthHandler struct {
|
||
rdb *redis.Client
|
||
tokenGenerator *TokenGenerator
|
||
ctx context.Context
|
||
}
|
||
|
||
type MFACreateChallengeRequest struct {
|
||
UserID string `json:"user_id"`
|
||
}
|
||
|
||
type MFAResponse struct {
|
||
ChallengeID string `json:"challenge_id"`
|
||
SupportedFactors []string `json:"supported_factors"`
|
||
ExpiresIn int `json:"expires_in"` // seconds
|
||
}
|
||
|
||
// MFAChallengeResponse MFA 验证通过后返回的 token 对
|
||
type MFAChallengeResponse struct {
|
||
AccessToken string `json:"access_token"`
|
||
RefreshToken string `json:"refresh_token"`
|
||
MFAVerified bool `json:"mfa_verified"`
|
||
TokenType string `json:"token_type"` // "Bearer"
|
||
}
|
||
|
||
// CreateMFAChallenge 在密码验证通过后调用，生成一个限时 challenge
|
||
func (h *AuthHandler) CreateMFAChallenge(w http.ResponseWriter, r *http.Request) {
|
||
var req MFACreateChallengeRequest
|
||
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
||
http.Error(w, "invalid request body", http.StatusBadRequest)
|
||
return
|
||
}
|
||
|
||
challengeID := uuid.New().String()
|
||
expiry := time.Now().Add(5 * time.Minute)
|
||
|
||
// 将 challenge 存入 Redis，5 分钟过期
|
||
key := fmt.Sprintf("mfa:challenge:%s", challengeID)
|
||
h.rdb.Set(h.ctx, key, fmt.Sprintf(`{"user_id":"%s","exp":%d}`, req.UserID, expiry.Unix()), 5*time.Minute)
|
||
|
||
json.NewEncoder(w).Encode(MFAResponse{
|
||
ChallengeID: challengeID,
|
||
SupportedFactors: []string{"totp", "webauthn"},
|
||
ExpiresIn: 300,
|
||
})
|
||
}
|
||
|
||
// SubmitMFAVerify 提交 MFA 码进行验证
|
||
func (h *AuthHandler) SubmitMFAVerify(w http.ResponseWriter, r *http.Request) {
|
||
var req struct {
|
||
ChallengeID string `json:"challenge_id"`
|
||
Factor string `json:"factor"` // "totp" or "webauthn"
|
||
Code string `json:"code"`
|
||
}
|
||
json.NewDecoder(r.Body).Decode(&req)
|
||
|
||
// 1. 校验 challenge 存在且未过期
|
||
userID, err := h.validateChallenge(req.ChallengeID)
|
||
if err != nil {
|
||
http.Error(w, "invalid or expired challenge", http.StatusUnauthorized)
|
||
return
|
||
}
|
||
|
||
// 2. 根据 factor 执行验证逻辑
|
||
switch req.Factor {
|
||
case "totp":
|
||
if !totp.Verify(userID, req.Code, 6, 1, time.Now()) {
|
||
http.Error(w, "invalid totp code", http.StatusUnauthorized)
|
||
return
|
||
}
|
||
case "webauthn":
|
||
// WebAuthn assertion verification...
|
||
}
|
||
|
||
// 3. 验证成功，发放 token
|
||
tokenPair, err := h.tokenGenerator.Generate(userID, map[string]interface{}{
|
||
"mfa_verified": true,
|
||
"session_id": req.ChallengeID,
|
||
})
|
||
if err != nil {
|
||
http.Error(w, "token generation failed", http.StatusInternalServerError)
|
||
return
|
||
}
|
||
|
||
json.NewEncoder(w).Encode(MFAChallengeResponse{
|
||
AccessToken: tokenPair.AccessToken,
|
||
RefreshToken: tokenPair.RefreshToken,
|
||
MFAVerified: true,
|
||
TokenType: "Bearer",
|
||
})
|
||
}
|
||
```
|
||
|
||
### 3.2 MFA-Verified Scope（精细粒度控制）
|
||
|
||
不同 API 对安全级别的请求不同。高敏感操作需要 `mfa_verified=true` 的 token。
|
||
|
||
```typescript
|
||
// 前端：根据操作敏感度判断是否需要触发 MFA
|
||
|
||
// decodeBase64URL JWT payload 解码 helper
|
||
function decodeBase64URL(base64url: string): string {
|
||
const base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
|
||
return atob(base64);
|
||
}
|
||
|
||
async function sensitiveAction(apiPath: string) {
|
||
const needsMFA = apiPath.match(/\/transfer|\/withdraw|\/settings-change/);
|
||
|
||
if (needsMFA) {
|
||
// 检查当前 token 是否已有 MFA 标记
|
||
const token = getToken();
|
||
const decoded = JSON.parse(decodeBase64URL(token.split('.')[1]));
|
||
|
||
if (!decoded.mfa_verified) {
|
||
// 先走 MFA flow，获取新 token
|
||
const freshToken = await requestMFAFlow();
|
||
setToken(freshToken);
|
||
}
|
||
}
|
||
|
||
return fetch(apiPath, {
|
||
headers: { Authorization: `Bearer ${getToken()}` },
|
||
});
|
||
}
|
||
```
|
||
|
||
```go
|
||
// 后端中间件：校验 Token 中的 MFA 级别
|
||
func MFAMiddleware(requiredLevel string) gin.HandlerFunc {
|
||
return func(c *gin.Context) {
|
||
tokenStr, _ := extractToken(c)
|
||
claims, err := validateJWT(tokenStr)
|
||
if err != nil {
|
||
c.AbortWithStatusJSON(401, gin.H{"error": "invalid token"})
|
||
return
|
||
}
|
||
|
||
if requiredLevel == "high" && claims.MFAVerified != true {
|
||
c.AbortWithStatusJSON(403, gin.H{
|
||
"error": "mfa_verification_required",
|
||
"required_level": "high",
|
||
})
|
||
return
|
||
}
|
||
|
||
c.Set("claims", claims)
|
||
c.Next()
|
||
}
|
||
}
|
||
|
||
// 使用示例
|
||
router.POST("/api/transfer", middleware.MFAMiddleware("high"), transferHandler)
|
||
router.GET("/api/profile", middleware.MFAMiddleware("low"), profileHandler)
|
||
```
|
||
|
||
### 3.3 Backup Codes（备用码）机制
|
||
|
||
当用户丢失手机或 TOTP app 无法使用时，Backup Codes 是最后的保底手段。
|
||
|
||
**设计要点:**
|
||
1. **一次性使用** — 每个码只能用一次，验证后立即标记已用
|
||
2. **预生成 + 安全存储** — 启用 TOTP 时同时生成 10 个码
|
||
3. **SHA-256 哈希存储** — 数据库中只存 hash，不存明文
|
||
4. **唯一显示给用户** — 用户需截图或抄写保存（离线场景）
|
||
|
||
```go
|
||
func GenerateBackupCodes(userID string) ([]string, []string) {
|
||
codes := make([]string, 10)
|
||
hashes := make([]string, 10)
|
||
for i := 0; i < 10; i++ {
|
||
b := make([]byte, 8)
|
||
rand.Read(b)
|
||
code := fmt.Sprintf("%08d", binary.BigEndian.Uint64(b) % 100000000)
|
||
codes[i] = code
|
||
hashes[i] = sha256.Sum256([]byte(code))
|
||
}
|
||
// hashes 存入数据库（一次性展示给用户）
|
||
return codes, hashes
|
||
}
|
||
|
||
func VerifyBackupCode(userID, code string) bool {
|
||
hash := sha256.Sum256([]byte(code))
|
||
ok := db.QueryRow("SELECT id FROM backup_codes WHERE user_id=? AND hash=?", userID, hash).Scan(...)
|
||
if ok {
|
||
// 立即删除，确保一次性
|
||
db.Exec("DELETE FROM backup_codes WHERE user_id=? AND hash=?", userID, hash)
|
||
}
|
||
return ok
|
||
}
|
||
```
|
||
|
||
> [!warning] 安全注意
|
||
> - Backup Codes 的强度等同于 8 位数字（1 亿种组合），**必须一次性使用**后销毁
|
||
> - 剩余可用码数量应反馈给前端（"还有 3 个备用码可用"），让用户心中有数
|
||
> - 使用 Backup Code 登录后，建议强制重新绑定 TOTP（视为设备变更）
|
||
> - 审计日志中单独标注 "auth_method: backup_code"
|
||
|
||
---
|
||
|
||
### 3.4 Session 管理与 Remember-Me
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> Unauthenticated
|
||
|
||
Unauthenticated --> PasswordValidated: 输入用户名 + 密码
|
||
PasswordValidated --> MFAChallenged: 需要 MFA
|
||
PasswordValidated --> Authorized: MFA skip (trusted device)
|
||
|
||
MFAChallenged --> Authorized: MFA verified
|
||
MFAChallenged --> PasswordValidated: MFA timeout
|
||
MFAChallenged --> Unauthenticated: cancel
|
||
|
||
Authorized --> SessionActive: 发放 session
|
||
SessionActive --> Authorized: token refresh
|
||
SessionActive --> Remembered: 勾选"记住我"
|
||
Remembered --> Authorized: 自动续期 (extended)
|
||
Remembered --> Unauthenticated: remember token expired
|
||
Authorized --> Unauthenticated: logout / revoke
|
||
```
|
||
|
||
| 策略 | 典型 TTL | 适用场景 |
|
||
|------|---------|---------|
|
||
| 标准 Session | 24h（配合 refresh token 滚动） | 日常办公 |
|
||
| Remember-Me | 7~30 天 | 个人账号，低敏感度 |
|
||
| No-Retain | 关闭 remember-me | 金融/医疗等高敏场景 |
|
||
|
||
> [!warning] Refresh Token 轮换（Rotation）
|
||
> 每次使用 refresh token 换 access token 时，都应同步颁发新的 refresh token，使旧的那个失效。这样可以：
|
||
> - 检测 replay 攻击（旧 refresh token 再次出现即意味着泄露）
|
||
> - 限制单个刷新令牌的总生命周期
|
||
> - Go 实现中使用 Redis Set NX 保证原子性
|
||
|
||
---
|
||
|
||
## 四、端到端实战流程
|
||
|
||
### 4.1 完整登录链路（含 MFA）
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
actor U as User
|
||
participant FE as Frontend (React)
|
||
participant BE as Backend (Go)
|
||
participant AS as Auth Server
|
||
participant Redis as Redis Store
|
||
|
||
U->>FE: 点击"登录"
|
||
FE->>FE: generate code_verifier + code_challenge
|
||
FE->>AS: 重定向到 auth server
|
||
AS->>U: 展示登录表单
|
||
|
||
U->>AS: 输入 username + password
|
||
AS->>AS: 验证密码 ✓
|
||
AS->>AS: 查询 MFA 状态
|
||
Note over AS: 如果用户有 TOTP → 需要 MFA<br/>如果没有 → 直接发 token
|
||
|
||
alt MFA Required
|
||
AS->>FE: redirect back with error=mfa_required
|
||
FE->>BE: POST /api/auth/challenge (with user info)
|
||
BE->>Redis: store challenge record
|
||
BE->>FE: return challenge_id
|
||
FE->>U: 显示 TOTP 输入框
|
||
U->>FE: 输入 6 位验证码
|
||
FE->>BE: POST /api/auth/mfa-verify
|
||
BE->>AS: 带 X-MFA-Challenge-ID + code 调 /token
|
||
AS->>AS: 验证 TOTP + challenge
|
||
AS->>BE: {access_token, refresh_token, mfa_verified:true}
|
||
BE->>FE: token pair
|
||
FE->>FE: save token in memory state
|
||
else MFA Not Required
|
||
AS->>FE: redirect back with authorization code
|
||
FE->>AS: exchange code + verifier for tokens
|
||
AS->>FE: {access_token, refresh_token}
|
||
FE->>FE: save token in memory state
|
||
end
|
||
|
||
U->>FE: 进入应用主页
|
||
```
|
||
|
||
### 4.2 设备信任机制
|
||
|
||
对于可信设备，用户可以跳过 MFA。这是用户体验和安全的关键平衡点。
|
||
|
||
```go
|
||
// 设备指纹生成与验证
|
||
func DeviceFingerprint(userAgent string, screenRes string, timezone string) string {
|
||
seed := userAgent + screenRes + timezone
|
||
h := sha256.Sum256([]byte(seed))
|
||
return hex.EncodeToString(h[:16]) // 128-bit fingerprint
|
||
}
|
||
|
||
// 保存信任记录
|
||
func TrustDevice(userID, deviceFP string) error {
|
||
key := fmt.Sprintf("device:trust:%s:%s", userID, deviceFP)
|
||
return rdb.Set(ctx, key, "trusted", 30*24*time.Hour).Err() // 30 天
|
||
}
|
||
|
||
// 验证时跳过 MFA
|
||
func SkipMFAIfTrusted(userID, deviceFP string) bool {
|
||
key := fmt.Sprintf("device:trust:%s:%s", userID, deviceFP)
|
||
val, _ := rdb.Get(ctx, key).Result()
|
||
return val == "trusted"
|
||
}
|
||
```
|
||
|
||
```typescript
|
||
// 前端：生成设备指纹
|
||
async function getDeviceFingerprint(): Promise<string> {
|
||
const data = [
|
||
navigator.userAgent,
|
||
`${screen.width}x${screen.height}`,
|
||
Intl.DateTimeFormat().resolvedOptions().timeZone,
|
||
new Date().getTimezoneOffset(),
|
||
].join('|');
|
||
|
||
const encoder = new TextEncoder();
|
||
const hashBuffer = await crypto.subtle.digest('SHA-256', encoder.encode(data));
|
||
const hashArray = Array.from(new Uint8Array(hashBuffer)).slice(0, 16);
|
||
return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
|
||
}
|
||
```
|
||
|
||
> [!tip] 设备信任的安全性边界
|
||
> - 设备指纹**不是**加密证明，仅作为用户体验优化
|
||
> - 核心保障依然在于 access token 的短期生命周期
|
||
> - 敏感操作（转账、修改密码）**不应**因设备信任而跳过 MFA
|
||
> - 建议定期重新验证（如每隔 7 天清除 trust 记录）
|
||
|
||
---
|
||
|
||
## 五、OpenID Connect（OIDC）扩展
|
||
|
||
OIDC 是在 OAuth2 之上的认证层，提供了标准化的身份令牌（Identity Token）。
|
||
|
||
```
|
||
OAuth2: Client → AS → "Here's an access token for reading resources"
|
||
OIDC: Client → AS → "Here's an access token AND here's who you are"
|
||
```
|
||
|
||
### 5.1 ID Token（JWT 格式）
|
||
|
||
```json
|
||
{
|
||
"iss": "https://auth.example.com",
|
||
"sub": "user_abc123",
|
||
"aud": ["client_id_xyz"],
|
||
"exp": 1715970000,
|
||
"iat": 1715966400,
|
||
"auth_time": 1715966350,
|
||
"amr": ["pwd", "otp"], // Authentication Methods References
|
||
"azp": "client_id_xyz",
|
||
"nonce": "random-nonce-value"
|
||
}
|
||
```
|
||
|
||
> [!note] amr (Authentication Methods References)
|
||
> `amr` 字段记录了认证方法。**这就是 MFA 信息在 OIDC 层面的体现**：
|
||
> - `["pwd"]` → 仅有密码认证
|
||
> - `["pwd", "otp"]` → 密码 + OTP（双因素完成）
|
||
> - `["pwd", "puk"]` → 密码 + 硬件密钥
|
||
>
|
||
> 前端解析 `id_token.amr` 即可知道用户当前的认证强度。
|
||
|
||
### 5.2 Auth Server 选型推荐
|
||
|
||
自建还是用托管方案？以下是主流选型对比：
|
||
|
||
| 方案 | 适合场景 | MFA 支持 | 开发成本 | 维护成本 |
|
||
|------|---------|---------|---------|---------|
|
||
| **Keycloak (开源)** | 企业内部、数据不出域 | TOTP / WebAuthn / Email OTP | 中 | 中（需运维） |
|
||
| **Auth0 (SaaS)** | 快速上线、预算充足 | 全量支持 + adaptive MFA | 低 | 极低 |
|
||
| **Cloudflare Access** | 边缘侧认证、API 网关 | 邮件 OTP / WebAuthn | 低 | 极低 |
|
||
| **自研 (Go + go-oauth2/oauth2)** | 高度定制化需求 | 完全自控 | 高 | 高 |
|
||
| **Supabase Auth** | 初创产品、BFF 架构 | TOTP (v2) | 低 | 极低 |
|
||
|
||
```mermaid
|
||
graph TD
|
||
A{"需要快速上线?"} -->|是| B["Auth0 / Supabase"]
|
||
A -->|否| C{"数据合规要求?"}
|
||
C -->|必须私有部署| D["Keycloak"]
|
||
C -->|无限制| E["自建方案"]
|
||
|
||
style B fill:#d4edda
|
||
style D fill:#fff3cd
|
||
style E fill:#f8d7da
|
||
```
|
||
|
||
> [!tip] 决策建议
|
||
> - **MVP / 创业公司**：直接用 Auth0，节省数周开发时间
|
||
> - **企业内网工具**：Keycloak + LDAP/AD 集成，一次投入长期受益
|
||
> - **高度敏感行业**：考虑自建（可控审计流程），但务必复用成熟开源库而非从零造轮子
|
||
|
||
---
|
||
|
||
## 七、安全最佳实践清单
|
||
|
||
> [!checklist] 生产环境 Checklist
|
||
|
||
### OAuth2 侧
|
||
- [ ] **必须使用 HTTPS**（TLS 1.2+），否则 token 在网络中转易被截取
|
||
- [ ] Authorization Code + **PKCE** 是所有公开客户端的标配
|
||
- [ ] Access Token 放在**内存**（不存 localStorage/sessionStorage）
|
||
- [ ] Refresh Token 使用 **HTTP-only, Secure, SameSite=Strict** Cookie 仅在后端
|
||
- [ ] 实现 **Refresh Token Rotation**（每次旋转，旧 token 立即作废）
|
||
- [ ] Token 设置合理的 TTL（Access: 15min~1hr，Refresh: 7~30 days）
|
||
- [ ] JWT 使用 **RS256/ES256**（非对称签名），避免 HS256 密钥泄漏风险
|
||
- [ ] 严格校验 `issuer`、`audience`、`expiry`、`nonce`
|
||
|
||
### MFA 侧
|
||
- [ ] TOTP 使用 **RFC 6238** 兼容库，不要自己实现底层密码学
|
||
- [ ] rate limiting：每个 IP 每 10 次失败锁定 5 分钟
|
||
- [ ] 考虑支持 **Backup Codes**（一次性备用码，最多 10 个）
|
||
- [ ] 优先推荐 **WebAuthn/FIDO2** 替代 SMS/TOTP（更抗钓鱼）
|
||
- [ ] SMS 验证码有效期不超过 **10 分钟**
|
||
- [ ] MFA 相关接口必须限制频率（不要让用户能爆破 6 位数字）
|
||
- [ ] 支持 **MFA enrollment revocation**（用户可随时禁用并重新配置）
|
||
|
||
### 架构侧
|
||
- [ ] Token 中**不存储敏感数据**（密码、MFA secret），只存元数据
|
||
- [ ] 审计日志：记录每次 MFA 验证尝试（成功/失败/IP/device）
|
||
- [ ] 敏感操作强制二次 MFA（即使 token 带有 `mfa_verified: true`）
|
||
- [ ] 实现 Token Revocation List（黑屏/注销时立即失效）
|
||
|
||
---
|
||
|
||
## 八、常见威胁模型分析
|
||
|
||
| 攻击类型 | 防御手段 |
|
||
|---------|---------|
|
||
| **Phishing（钓鱼）** | WebAuthn（origin-binding 天然免疫）、DNS-over-HTTPS |
|
||
| **Replay Attack（重放）** | PKCE、Nonce 校验、Refresh Token Rotation |
|
||
| **Token Theft（窃听/存储）** | Short-lived Access Token、HTTPS-only、SameSite Cookie |
|
||
| **Brute Force（爆破 MFA）** | Rate Limiting、Account Lockout |
|
||
| **Session Hijacking** | HttpOnly Cookie、CSRF Token、Device Binding |
|
||
| **SIM Swap（短信劫持）** | 优先 TOTP/WebAuthn、SMS 仅作为 fallback |
|
||
|
||
---
|
||
|
||
## 关联笔记
|
||
|
||
- [[hhs/DEV/Security/Basics/RSA-and-ECC]]
|
||
- [[hhs/DEV/Security/JWT-Deep-Dive]]
|
||
- [[hhs/DEV/Go/Backend/Redis-Patterns]]
|
||
- [[hhs/DEV/React/frontend-state-management]]
|