IWish Auth 开发者文档

IWish Auth 接入分为平台配置、业务 App 开发、授权和上线验收四部分。不要让业务 App 开发者自行创建飞书应用或复制 Supabase 配置。

1. 角色分工

角色	负责内容
IWish Auth 平台管理员	注册 App、创建 OAuth client、开通组织、审核 Manifest、分配角色
业务 App 开发者	接入 SDK、替换本地登录与角色判断、保留业务数据授权
业务负责人	确认权限颗粒度、角色模板和迁移窗口
安全/运维	管理 secrets、callback、生产发布和审计证据

2. 标准接入顺序

为 App 确定唯一、稳定、全小写的 appKey。
盘点现有角色和保护动作，形成权限映射表。
编写并本地校验 auth.manifest.json。
管理员在 IWish Auth 注册 App、同步 Manifest。
管理员创建 confidential OAuth client 和精确 callback。
App 服务端接入 SDK 登录、callback 和 App session。
使用 requirePermission 替换本地角色判断。
按需读取 clientAssignments，但保留业务数据授权。
删除本地密码、登录入口和角色分配写入口。
在 dev/staging 完成安全、回归和回滚演练后直接切换。

3. 登录数据流

业务 App -> IWish Auth Portal -> 飞书或邮箱登录
        <- authorization code + state
业务 App 服务端 -> /v1/sso/token -> opaque App session
业务请求 -> /v1/sso/session -> App scoped context

业务 App 浏览器只保存自身 HttpOnly session cookie。它不接触飞书 token、Supabase refresh token、OAuth client secret 或 Auth 数据库连接。

4. 权限数据流

auth.manifest.json
  -> Manifest CLI 预检/同步
  -> IWish Auth permissions + roles
  -> 管理员按组织给用户分配 App 角色
  -> App session 返回当前 App permissions
  -> 业务路由 requirePermission

权限由 IWish Auth 统一定义和分配，业务 App 只执行权限结果。业务记录归属、字段可见性和客户数据隔离继续由业务 App 自己处理。

5. 客户项目数据流

飞书同步提供公司部门和员工目录；IWish Auth 管理员独立创建客户项目，再把 active 飞书员工以多个项目职责绑定到项目。业务 App 从 session 的 clientAssignments 获取当前员工的有效项目分工。

外部客户账号不是创建客户项目的前置条件。一个客户项目可以在没有任何外部账号的情况下存在和分配内部服务团队。

6. 禁止的接入方式

业务 App 直接调用飞书通讯录或飞书 OAuth。
从浏览器直接调用 /v1/sso/token。
把 clientSecret 放入前端环境变量。
信任 x-user-id、x-role 等可伪造身份 Header。
继续在业务 App 创建密码或分配统一角色。
用 clientAssignments 代替 requirePermission。
让多个 App 共用同一个 OAuth client 或 session cookie。