auth-permission

Auth & Permission

Reference sources:OAuth 2.0 RFC 6749、JWT RFC 7519, RBAC model

Applicable scenarios

API authentication and authorization design
Multi-role permission system
Multi-tenant isolation
Field-level permissions
Third-party integration (OAuth)

Core distinctions

认证（Authentication）：你是谁？
  - 验证身份
  - 失败返回 401
  - 例：token 无效 / 过期

Authorization: What can you do?

Verify permissions
Return 403 on failure
Example: logged in but not authorized to access the resource

Tenant isolation: Which organization are you in?

Cross-organization data isolation
Return 403 or 404 on failure

Resource ownership: Who does this resource belong to?

Users can only operate on their own resources
Return 403 or 404 on failure


## 认证方式

### 1. Bearer Token（最常见）

```text
Authorization: Bearer eyJhbGc...

适用：用户 API、移动 App
实现：通常用 JWT

2. API Key

方式 1：Header
  X-API-Key: sk_live_abc123

方式 2：Query（不推荐，易泄露）
  /api/v1/users?api_key=xxx

适用：服务到服务、SDK、Webhook 验签

3. OAuth 2.0

适用：第三方接入、开放平台
流程：
  1. 用户授权（authorization_code）
  2. 换取 token
  3. 调用 API

4. Session Cookie

Cookie: session=abc123

适用：浏览器同站调用
注意：CSRF 防护必备

5. Basic Auth (internal only)

Authorization: Basic base64(username:password)

适用：内部工具、最简单接入
不适用：公开 API

JWT structure

header.payload.signature

Payload 标准字段（claims）：
  iss: 签发者
  sub: 用户 ID
  aud: 接收方
  exp: 过期时间
  iat: 签发时间
  jti: JWT ID（用于撤销）

自定义字段：
  user_id: usr_abc
  email: user@example.com
  roles: ["admin", "developer"]
  tenant_id: org_xyz

注意：
  - JWT 只能验证不能撤销（除非加 jti 黑名单）
  - 短过期时间（15min~1h）+ refresh token
  - 不要存敏感信息（payload 可解码）

Permission models

RBAC (role-based permissions)

用户 → 角色 → 权限

角色示例：
  - admin：所有权限
  - manager：管理用户和订单
  - employee：查看订单
  - guest：仅查看公开资源

权限示例：
  - users:read
  - users:write
  - users:delete
  - orders:read
  - orders:approve

ABAC (attribute-based permissions)

基于属性的权限：
  - 用户属性：部门 / 角色 / 权限组
  - 资源属性：所有者 / 状态 / 标签
  - 环境属性：时间 / IP / 设备

适用：复杂权限场景（如金融审批）

Resource ownership

即使有权限，还要检查资源归属：

用户 A 是 manager，能 read orders
但只能 read 自己组织的 orders
不能 read 用户 B 的组织的 orders

实现：
  WHERE tenant_id = current_user.tenant_id
  AND owner_id = current_user.id  -- 个人资源

Permission matrix

## 权限矩阵：[模块名]

| 操作 | guest | user | manager | admin |
|------|-------|------|---------|-------|
| 查看公开商品 | ✅ | ✅ | ✅ | ✅ |
| 查看自己订单 | ❌ | ✅ self | ✅ team | ✅ all |
| 创建订单 | ❌ | ✅ | ✅ | ✅ |
| 取消订单 | ❌ | ✅ self | ✅ team | ✅ |
| 修改订单状态 | ❌ | ❌ | ✅ team | ✅ |
| 退款 | ❌ | ❌ | ❌ | ✅ |
| 删除用户 | ❌ | ❌ | ❌ | ✅ |

注：
  self = 仅自己的资源
  team = 仅本团队/组织的
  all = 所有

Field-level permissions

不同角色看到的字段不同：

GET /users/{id}

普通用户看自己：
{
  "id", "email", "name", "phone",
  "address", "preferences",
  "created_at"
}

管理员看任何用户：
{
  "id", "email", "name", "phone",
  "address", "preferences",
  "ip_address", "last_login",
  "risk_score", "internal_notes",
  "created_at"
}

实现：响应序列化时根据角色筛选字段

Multi-tenant isolation

方式 1：URL 显式
  /api/v1/orgs/{org_id}/users
  优点：明确
  缺点：URL 长

方式 2：Header
  X-Tenant-Id: org_xyz
  优点：URL 简洁
  缺点：易忘记设置

方式 3：从 token 提取（推荐）
  JWT payload 含 tenant_id
  服务端自动加过滤条件
  优点：安全 + 简洁
  缺点：跨租户场景需要特殊处理

任何方式都要服务端验证：
  user.tenant_id == resource.tenant_id

Output format

## 认证鉴权设计：[API 模块]

### 认证方式
- 用户 API：Bearer Token (JWT)
  - 过期时间：1 小时
  - Refresh Token：30 天
- 服务到服务：API Key
- Webhook：HMAC 签名

### 角色定义
- guest：未登录
- user：普通用户
- manager：团队管理员
- admin：系统管理员

### 权限矩阵
[见上方表格]

### 租户隔离
- 方式：JWT 含 tenant_id，服务端自动过滤
- 跨租户：仅 admin 可通过 ?tenant_id= 显式指定

### 字段权限
- 普通用户：脱敏字段（手机号显示 138****8000）
- 管理员：完整字段 + 内部字段

### 错误处理
- 401：token 缺失/无效/过期 → token_invalid / token_expired
- 403：已认证但无权限 → permission_denied
- 404：（隐私考虑）资源不存在 → not_found

Workflow

1. 选择认证方式（Bearer / API Key / OAuth）
2. 列出角色清单
3. 列出操作清单
4. 画权限矩阵
5. 设计租户隔离方式
6. 标注字段级权限（如有）
7. 设计错误处理（401 vs 403 vs 404）
8. 输出鉴权说明

Quality self-check

□ 是否区分 401（认证）和 403（鉴权）
□ 权限矩阵是否覆盖所有角色和操作
□ 是否考虑了资源归属（不只看角色）
□ 是否考虑了多租户隔离
□ 字段级权限是否定义
□ Token 过期策略是否合理（不要太久）
□ 是否避免了 token 在 URL 中
□ 错误响应是否泄露隐私

Common pitfalls

Simplifying permissions to "login required"— all users can do everything
Checking only roles, not ownership— a manager can see other teams' data
Tenant isolation vulnerabilities— forgetting to add tenant_id filtering
JWT expiration time too long— 24 hours or even no expiration → hard to revoke
Sensitive information in JWT payload— payload can be decoded
API Key in URL— leaked in logs
Inconsistent 403 and 404— for privacy, should uniformly return 404 to hide existence
Missing field permissions— returns all fields, relies on frontend hiding

Supporting templates

templates/auth-permission-template.md — permission matrix + JWT payload + authentication flow templates

Collaboration with other skills

上游：
  resource-modeling → 资源清单
  endpoint-design → 端点清单

平行：
  error-handling → 401/403 错误码细化

下游：
  openapi-mock → 安全 schema
  转交安全工程师 → 安全评审
  转交后端 → 实现鉴权中间件

Related references

references/auth-permission-guide.md — selection decision tree, token type comparison, permission model comparison (RBAC/ABAC/ReBAC), big tech paradigms (Stripe Keys / GitHub Fine-grained PAT / AWS IAM), field-level permissions, multi-tenant three-layer defense, security self-check