vault backup: 2026-08-08 19:01:04

This commit is contained in:
2026-08-08 19:01:04 +08:00
parent 1a4a83bc67
commit e2975eb86b
46 changed files with 9370 additions and 0 deletions
+261
View File
@@ -0,0 +1,261 @@
---
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 权限模型]]
+261
View File
@@ -0,0 +1,261 @@
---
tags: [pattern/auth, rbac, role-inheritance, separation-of-duty, access-control]
create time: 2026-08-08 15:30
update time: 2026-08-08 15:30
---
# RBAC 权限模型
## 概述
RBAC(Role-Based Access Control)是一种基于角色分配访问权限的模型,是目前企业级应用中最主流的权限管理方案。它的核心思想是**将用户与角色关联,而非将用户与权限直接绑定**——这层间接大大降低了权限管理的复杂度。
## 五张表设计
### 表结构定义
```sql
-- 1. 用户表
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(64) NOT NULL UNIQUE,
password_hash VARCHAR(128) NOT NULL,
email VARCHAR(128),
status TINYINT DEFAULT 1 COMMENT '1-active 0-disabled',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- 2. 角色表
CREATE TABLE roles (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(64) NOT NULL UNIQUE,
description VARCHAR(256),
is_super TINYINT DEFAULT 0 COMMENT '是否超级管理员',
parent_id BIGINT DEFAULT NULL COMMENT '父角色ID(用于继承)',
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- 3. 权限表
CREATE TABLE permissions (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
code VARCHAR(128) NOT NULL UNIQUE COMMENT '权限标识如 user:create',
resource VARCHAR(64) NOT NULL COMMENT '资源类型: user/order/bucket',
action VARCHAR(64) NOT NULL COMMENT '操作: create/read/update/delete',
description VARCHAR(256)
);
-- 4. 用户-角色(多对多)
CREATE TABLE user_roles (
user_id BIGINT NOT NULL,
role_id BIGINT NOT NULL,
PRIMARY KEY (user_id, role_id),
FOREIGN KEY (user_id) REFERENCES users(id),
FOREIGN KEY (role_id) REFERENCES roles(id)
);
-- 5. 角色-权限(多对多)
CREATE TABLE role_permissions (
role_id BIGINT NOT NULL,
permission_id BIGINT NOT NULL,
PRIMARY KEY (role_id, permission_id),
FOREIGN KEY (role_id) REFERENCES roles(id),
FOREIGN KEY (permission_id) REFERENCES permissions(id)
);
```
### ER 关系图
```mermaid
erDiagram
users ||--o{ user_roles : "belongs to"
roles ||--o{ user_roles : "assigned via"
roles ||--o{ role_permissions : "has"
permissions ||--o{ role_permissions : "granted through"
users {
BIGINT id PK
varchar username
varchar password_hash
tinyint status
}
roles {
BIGINT id PK
varchar name
varchar description
tinyint is_super
BIGINT parent_id FK
}
permissions {
BIGINT id PK
varchar code UK
varchar resource
varchar action
}
user_roles {
BIGINT user_id PK
BIGINT role_id PK
}
role_permissions {
BIGINT role_id PK
BIGINT permission_id PK
}
```
## 核心原理
### 用户 → 角色 → 权限 的两层映射
传统 ACL(Access Control List)直接将用户和权限绑定:
```
Alice → read_order, write_order, delete_user
Bob → read_order
Carol → read_order, write_bucket
```
问题在于当需要批量授权时(比如给所有财务加 20 个权限),必须逐一修改每个用户的权限列表。
RBAC 引入角色层后变成:
```
角色定义:
Finance → 20 个权限(包括 read_order, export_report...)
Operator → 10 个权限(read_order, write_bucket...)
用户分配:
Alice → Finance
Bob → Operator
Carol → Operator
```
批量调整只需改角色的权限映射,不影响用户。
### 超级管理员与普通角色的继承
超级管理员通常拥有所有权限。但直接给 super_admin 角色分配几百条权限记录既繁琐也不优雅。更合理的做法是**继承机制**:
```sql
-- 在 roles 表中用 parent_id 表示层级
INSERT INTO roles (name, is_super, parent_id) VALUES ('super_admin', 1, NULL);
INSERT INTO roles (name, is_super, parent_id) VALUES ('admin', 0, (SELECT id FROM roles WHERE name='super_admin'));
INSERT INTO roles (name, is_super, parent_id) VALUES ('finance', 0, (SELECT id FROM roles WHERE name='admin'));
```
查询某用户全部权限时递归展开:
```go
func (m *AuthManager) GetUserPermissions(ctx context.Context, userID int64) ([]string, error) {
// 1. 查用户所有角色
roles, _ := m.db.QueryContext(ctx, `
SELECT r.id, r.is_super, r.parent_id FROM user_roles ur
JOIN roles r ON ur.role_id = r.id WHERE ur.user_id = ?`, userID)
var allCodes []string
for roles.Next() {
var role Role
roles.Scan(&role.ID, &role.IsSuper, &role.ParentID)
if role.IsSuper {
return []string{"*"}, nil
}
perms, _ := m.getRolePermissionCodes(ctx, role.ID)
allCodes = append(allCodes, perms...)
}
return deduplicate(allCodes), nil
}
```
### 互斥职责分离(Separation of Duty)
某些场景下同一人不能同时拥有冲突的角色,例如:
- **申请人与审批人不可同一人** — 你不能批准自己的报销单
- **出纳与会计不可兼任** — 财务内控基本要求
实现方式是在角色创建或用户分配时做冲突检测:
```sql
-- 假设 conflict_roles 表定义互斥关系
CREATE TABLE conflict_roles (
role_a BIGINT NOT NULL,
role_b BIGINT NOT NULL,
PRIMARY KEY (role_a, role_b)
);
-- 分配角色前检查
SELECT COUNT(*) FROM conflict_roles cr
JOIN user_roles ur ON ur.role_id IN (cr.role_a, cr.role_b)
WHERE ur.user_id = ? AND cr.role_a = ? AND cr.role_b = ?
```
> [!WARNING]
> 互斥约束应该在**分配角色层**校验,而不是每次鉴权时检查。前者是策略问题,后者是执行问题——在入口处挡住比到处拦击效率高得多。
### 动态权限加载流程
```mermaid
sequenceDiagram
participant User as 用户
participant API as 认证服务
participant DB as 数据库
participant Redis as 缓存
User->>API: 登录
API->>DB: 查询用户所有角色
DB-->>API: 返回角色列表
API->>DB: 查询各角色的权限码
DB-->>API: 返回权限码列表
API->>Redis: 写入用户权限缓存 (TTL=2h)
Redis-->>API: OK
API-->>User: 登录成功 + Token
```
> [!TIP]
> 登录时将完整权限树缓存在 Redis 中,鉴权接口只需 O(1) 读取缓存。权限变更时主动删除对应用户的缓存条目,实现最终一致。不要每次都查库。
## 代码示例:权限中间件(Go)
```go
type ContextKey string
const PermissionKey ContextKey = "permissions"
func AuthMiddleware(h Handler) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
token := extractToken(r)
claims, _ := jwt.Parse(token)
userID := claims.UserID
// 从 Redis 获取权限
perms, err := cache.GetPermissions(r.Context(), userID)
if err != nil {
perms = loadFromDB(userID)
cache.Set(userID, perms, 2*time.Hour)
}
ctx := context.WithValue(r.Context(), PermissionKey, perms)
h.ServeHTTP(w, r.WithContext(ctx))
}
}
// 检查某个权限
func HasPermission(ctx context.Context, required string) bool {
perms := ctx.Value(PermissionKey).([]string)
for _, p := range perms {
if p == "*" || p == required {
return true
}
}
return false
}
```
## 实践场景
| 场景 | 选型建议 |
|------|---------|
| 小型系统(用户 < 100) | 简单角色 + 硬编码判断即可,不必上完整 RBAC |
| 中型业务系统 | 标准五表 RBAC + Redis 缓存 |
| 平台型 SaaS | RBAC + 租户隔离(每租户可自定义角色) |
| 强合规要求(金融/医疗) | RBAC + SoD 互斥约束 + 完整审计日志 |
## 关联笔记
- [[OAuth2 与 JWT]]