---
tags: [pattern/auth, oauth2, jwt, token-authentication, refresh-token]
create time: 2026-08-08 16:00
update time: 2026-08-08 16:00
---

# OAuth2 与 JWT

## 概述

OAuth2 是业界标准的授权框架，定义了四种获取访问令牌的流程。JWT（JSON Web Token）则是令牌本身的一种通用格式。二者配合使用构成了现代互联网最常见的认证/授权方案：OAuth2 负责"你是谁、你能做什么"，JWT 负责"如何传递这些信息"。

## OAuth2 四种授权模式详解

### Authorization Code — 最安全的服务端模式

**适用场景**：传统 Web 应用、后端服务调用第三方 API。

```mermaid
sequenceDiagram
    participant User as 用户浏览器
    participant Client as 客户端应用
    participant Auth as 授权服务器
    participant Resource as 资源服务器
    
    User->>Client: 点击"用 Google 登录"
    Client->>User: 重定向到授权端点<br/>？response_type=code&client_id=&redirect_uri=&scope=
    User->>Auth: 登录并授权
    Auth->>User: 重定向回 redirect_uri?code=XXX
    User->>Client: 携带 authorization code
    Client->>Auth: POST /token (code + client_secret)
    Auth-->>Client: access_token + id_token + refresh_token
    Client->>Resource: GET /api/profile (Bearer token)
    Resource-->>Client: 用户数据
```

核心要点：
- **code 是一次性的短期凭证**（通常有效期 5 分钟），换取 token 的过程在后端完成，浏览器拿不到 token。
- `client_secret` 只存在于服务端通信中，前端 SPA 不应该持有它。
- 回调时建议校验 `state` 参数防止 CSRF。

> [!NOTE]
> PKCE 扩展：对于无法安全存储 `client_secret` 的场景（移动 App、SPA），RFC 7636 定义的 PKCE（Proof Key for Code Exchange）通过 `code_verifier` / `code_challenge` 对来替代 `client_secret`，使 Authorization Code 对所有客户端类型都是安全的。

### Implicit — 已废弃

曾用于纯前端 SPA 场景，直接返回 access_token：
```
redirect_uri?access_token=XXX&expires_in=3600
```

问题在于 **token 暴露在前端**——可以存入 localStorage、被 XSS 窃取、无法撤销。IETF 已在 RFC 6819 中明确标记为过时，推荐使用 Authorization Code + PKCE 替代。

### Password — 不推荐的第一方应用模式

用户直接向授权服务器提交用户名和密码：
```http
POST /token
grant_type=password&username=user@example.com&password=secret
```

优点是实现简单。但问题是：
- 客户端等同于拿到了用户的密码，**违背了 OAuth 的信任委派原则**。
- 无法在不换密码的前提下撤销特定客户端的访问。
- 仅适用于你完全信任的第一方应用。

### Client Credentials — 机器间通信

没有用户参与，客户端用自己的身份申请令牌：
```http
POST /token
grant_type=client_credentials&client_id=&client_secret=
```

典型场景：后台定时任务、微服务之间的内部调用、CI/CD 流水线拉取制品仓库。

### 四种模式对比

| 维度 | Authorization Code | Implicit | Password | Client Credentials |
|------|-------------------|----------|----------|-------------------|
| 涉及主体 | 用户 + 客户端 | 用户 + 客户端 | 用户 + 客户端 | 客户端 |
| token 暴露风险 | 低（后端交换） | **高**（前端可见） | **极高** | 无（无用户） |
| 是否需要 client_secret | 推荐（PKCE 可选） | 不适用 | 不适用 | **必需** |
| 当前状态 | 标准推荐 | 已废弃 | 受限使用 | 标准推荐 |
| 适用环境 | Web / 移动端 | ~~SPA~~ → 转 Code+PKCE | 第一方 App | 服务端互信 |

## JWT 结构

JWT 由三段 Base64Url 编码的字符串用 `.` 拼接而成：

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.  .  cCpliwZISlC_ddV2aOKXVuUFtF4QdBSgOzAWo0XihXA
         Header              Payload            Signature
```

### Header

```json
{
  "alg": "RS256",
  "typ": "JWT"
}
```

指定签名算法和令牌类型。

### Payload（Claim 集）

```json
{
  "sub": "user_12345",
  "name": "Alice",
  "role": "admin",
  "permissions": ["order:read", "order:write", "bucket:manage"],
  "iat": 1690000000,
  "exp": 1690003600,
  "jti": "uuid-v4-here"
}
```

标准保留声明：
- `iss`（Issuer）— 签发者
- `sub`（Subject）— 主题/用户标识
- `aud`（Audience）— 接收方
- `exp`（Expiration）— 过期时间
- `iat`（Issued At）— 签发时间
- `jti`（JWT ID）— 唯一标识，支持撤销

> [!WARNING]
> 绝对不要把敏感信息（密码、身份证号）放在 JWT payload 中。JWT 只是 Base64 编码而非加密，任何人都可以解码阅读。需要保密就使用 JWE（加密型 JWT）。

### Header + Payload → Signature

```
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)
```

或用 RSA 私钥签名（RS256）：
```
RSA-SHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), privateKey)
```

## HS256 vs RS256 签名算法选择

| 维度 | HS256（对称） | RS256（非对称） |
|------|--------------|----------------|
| 密钥 | 单一 shared secret | 公钥公开 / 私钥保密 |
| 验证方 | 必须持有密钥 | 只需公钥 |
| 适用场景 | 单体应用、内网服务 | 微服务、第三方集成 |
| 撤销能力 | 几乎不可撤销 | 可通过黑名单或短生命周期缓解 |
| 性能 | 更快（AES 级别运算） | 略慢（RSA 运算） |
| 安全风险 | 密钥泄露 = 所有 token 可伪造 | 仅私钥泄露才有危险 |

> [!TIP]
> 面试常考点：为什么微服务架构推荐 RS256？因为每个微服务只需要验证公钥而不需要持有签发私钥，即使某个服务被攻陷，攻击者也无法伪造其他服务的 token。HS256 要求所有服务共享同一个密钥，任何一台机器的密钥泄漏都会导致全局信任崩溃。

## Refresh Token 轮换机制

Access Token 生命周期短（5~15 分钟），不适合频繁让用户重新登录。Refresh Token 用于无声续期，但必须设计得当以防止重放攻击。

### 旋转流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Auth as 认证服务器
    participant Store as Token Store
    
    Note over Client,Store: 首次登录
    Auth->>Store: 存储 refresh_token (RT1) <-> user_id
    Auth-->>Client: RT1 + AT1（短效）
    
    Note over Client,Store: Access Token 过期后刷新
    Client->>Auth: POST /refresh {refresh_token: RT1}
    Auth->>Store: 验证 RT1 有效性且未被吊销
    Store-->>Auth: 匹配成功
    Auth->>Store: 删除 RT1，插入 RT2
    Auth-->>Client: RT2 + AT2
    
    Note over Client,Store: RT2 再次用于刷新（正常）
    Client->>Auth: POST /refresh {refresh_token: RT2}
    Auth->>Store: 验证 RT2...
    
    Note over Client,Store: RT1 被重放（攻击者窃取了旧 RT1）
    Client->>Auth: POST /refresh {refresh_token: RT1}
    Auth->>Store: 查找 RT1 → 不存在！
    Auth-->>Client: 401 Unauthorized ⚠️ 检测到重放
```

关键设计决策：
1. **每次刷新都生成新的 Refresh Token**（Rotation），旧的立即失效。
2. **如果同一个 Refresh Token 出现两次**：第一次按正常流程处理（生成新 Token），第二次判定为窃听攻击，同时**级联销毁该用户的所有 token 并要求重新登录**。
3. Refresh Token 比 Access Token 更严格地保管——存放在 HttpOnly Cookie 而非 localStorage。

### 代码示例（Go 伪代码）

```go
func (m *AuthManager) RotateRefreshToken(ctx context.Context, rt string) (newAT, newRT string, err error) {
    record, err := m.store.GetRefreshToken(ctx, rt)
    if err != nil {
        return "", "", fmt.Errorf("invalid refresh token")
    }
    
    // 幂等检查：如果这个 RT 已经被使用过，触发全量吊销
    if record.ConsumedAt != nil {
        m.store.RevokeAllUserTokens(ctx, record.UserID)
        return "", "", ErrSuspiciousReplay
    }
    
    // 标记旧 RT 已消费，创建新 RT
    now := time.Now()
    store.UpdateRefreshTokenConsumed(ctx, rt, now)
    newRT = generateToken(record.UserID, store.RandomNonce())
    
    return m.issueAccessToken(ctx, record.UserID), newRT, nil
}
```

## Token 黑名单 vs Token 白名单

| 方案 | 实现方式 | 优点 | 缺点 |
|------|---------|------|------|
| **黑名单** | 撤销时将 JWT jti 加入 Redis Set | 实现简单，无需改 Token 结构 | 随时间累积占用空间，需定期清理 |
| **白名单** | 服务端保存每条合法会话记录 | 天然支持细粒度控制（设备管理、远程注销） | 每次请求都要查库/缓存，有性能开销 |

实际生产中常用混合策略：
- **短生命周期 Access Token**（5 分钟）+ 本地校验（无需网络查询）
- **Refresh Token 存储在 Redis**，每次刷新做一次性校验
- **特殊场景下的黑名单**用于主动登出、密码修改后的批量踢人

## 实践场景：完整认证流

```mermaid
sequenceDiagram
    participant Client as 前端
    participant AuthSrv as 认证服务
    participant TokenSrv as Token 服务
    participant API as 业务 API
    
    Client->>AuthSrv: POST /login (username/password)
    AuthSrv->>AuthSrv: 验证凭据
    AuthSrv->>TokenSrv: 签发 RS256-signed JWT
    TokenSrv-->>AuthSrv: AT + RT
    AuthSrv-->>Client: 设置 Cookie(AT, RT) + 302 /dashboard
    
    Note over Client,API: 后续请求
    Client->>API: GET /api/orders (Cookie: AT)
    API->>TokenSrv: 验签 AT（公钥本地验证，零网络调用）
    TokenSrv-->>API: valid {sub: user_123, role: admin}
    API-->>Client: JSON response
```

> [!NOTE]
> 一个常见的误解：JWT ≠ 会话管理。JWT 只是一种**自包含的令牌格式**，它本身不提供会话管理能力。是否用数据库存 session、是否支持远程撤销、是否限制单设备登录——这些都是独立的架构决策，与选用 JWT 还是 opaque token 无关。

## 关联笔记

- [[RBAC 权限模型]]