Ejecuta cualquier Skill en Manus
con un clic

Ejecuta cualquier Skill en Manus con un clic

Comenzar

$pwd:

auth-permission

Name: Auth Permission
Author: zhaoxuya520

// 设计 API 认证鉴权和权限矩阵时使用。适用于多角色系统、租户隔离、字段级权限。优先使用 OAuth 2.0 / JWT + RBAC + 资源归属检查。

Ejecutar en Manus

$ git log --oneline --stat

stars:3

forks:2

updated:19 de mayo de 2026, 09:01

Explorador de archivos

3 archivos

SKILL.md

readonly

name	auth-permission
description	设计 API 认证鉴权和权限矩阵时使用。适用于多角色系统、租户隔离、字段级权限。优先使用 OAuth 2.0 / JWT + RBAC + 资源归属检查。

认证鉴权（Auth & Permission）

参考来源：OAuth 2.0 RFC 6749、JWT RFC 7519、RBAC 模型

适用场景

API 的认证鉴权设计
多角色权限系统
多租户隔离
字段级权限
第三方集成（OAuth）

核心区分

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

鉴权（Authorization）：你能做什么？
  - 验证权限
  - 失败返回 403
  - 例：已登录但无权访问该资源

租户隔离：你在哪个组织？
  - 跨组织数据隔离
  - 失败返回 403 或 404

资源归属：这个资源属于谁？
  - 用户只能操作自己的资源
  - 失败返回 403 或 404

认证方式

1. Bearer Token（最常见）

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（仅内部）

Authorization: Basic base64(username:password)

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

JWT 结构

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 可解码）

权限模型

RBAC（角色权限）

用户 → 角色 → 权限

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

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

ABAC（属性权限）

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

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

资源归属

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

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

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

权限矩阵

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

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

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

字段级权限

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

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"
}

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

多租户隔离

方式 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

输出格式

## 认证鉴权设计：[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

工作流程

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

质量自检

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

常见坑

把权限简化为"需要登录"——所有用户能做所有事
只检查角色不检查归属——manager 能看其他 team 的数据
租户隔离漏洞——忘记加 tenant_id 过滤
JWT 过期时间太长——24 小时甚至无过期 → 撤销难
敏感信息进 JWT payload——payload 可解码
API Key 在 URL——日志泄露
403 和 404 不一致——隐私考虑应统一返回 404 隐藏存在性
字段权限缺失——返回所有字段，靠前端隐藏

配套模板

templates/auth-permission-template.md — 权限矩阵 + JWT payload + 认证流程模板

与其他 skill 的协作

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

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

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

认证鉴权（Auth & Permission）

参考来源：OAuth 2.0 RFC 6749、JWT RFC 7519、RBAC 模型

适用场景

API 的认证鉴权设计
多角色权限系统
多租户隔离
字段级权限
第三方集成（OAuth）

核心区分

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

鉴权（Authorization）：你能做什么？
  - 验证权限
  - 失败返回 403
  - 例：已登录但无权访问该资源

租户隔离：你在哪个组织？
  - 跨组织数据隔离
  - 失败返回 403 或 404

资源归属：这个资源属于谁？
  - 用户只能操作自己的资源
  - 失败返回 403 或 404

认证方式

1. Bearer Token（最常见）

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（仅内部）

Authorization: Basic base64(username:password)

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

JWT 结构

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 可解码）

权限模型

RBAC（角色权限）

用户 → 角色 → 权限

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

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

ABAC（属性权限）

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

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

资源归属

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

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

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

权限矩阵

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

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

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

字段级权限

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

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"
}

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

多租户隔离

方式 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

输出格式

## 认证鉴权设计：[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

工作流程

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

质量自检

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

常见坑

把权限简化为"需要登录"——所有用户能做所有事
只检查角色不检查归属——manager 能看其他 team 的数据
租户隔离漏洞——忘记加 tenant_id 过滤
JWT 过期时间太长——24 小时甚至无过期 → 撤销难
敏感信息进 JWT payload——payload 可解码
API Key 在 URL——日志泄露
403 和 404 不一致——隐私考虑应统一返回 404 隐藏存在性
字段权限缺失——返回所有字段，靠前端隐藏

配套模板

templates/auth-permission-template.md — 权限矩阵 + JWT payload + 认证流程模板

与其他 skill 的协作

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

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

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

auth-permission

认证鉴权（Auth & Permission）

适用场景

核心区分

认证方式

1. Bearer Token（最常见）

2. API Key

3. OAuth 2.0

4. Session Cookie

5. Basic Auth（仅内部）

JWT 结构

权限模型

RBAC（角色权限）

ABAC（属性权限）

资源归属

权限矩阵

字段级权限

多租户隔离

输出格式

工作流程

质量自检

常见坑

配套模板

与其他 skill 的协作

相关参考

Más de este repositorio

Más de este repositorio

认证鉴权（Auth & Permission）

适用场景

核心区分

认证方式

1. Bearer Token（最常见）

2. API Key

3. OAuth 2.0

4. Session Cookie

5. Basic Auth（仅内部）

JWT 结构

权限模型

RBAC（角色权限）

ABAC（属性权限）

资源归属

权限矩阵

字段级权限

多租户隔离

输出格式

工作流程

质量自检

常见坑

配套模板

与其他 skill 的协作

相关参考