262 lines
9.8 KiB
Markdown
262 lines
9.8 KiB
Markdown
---
|
||
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 权限模型]]
|