权限管理
本文档介绍飞书插件的 OAuth 授权机制和权限管理。
授权模式
飞书插件支持两种授权模式：
1. 用户身份授权 (User Access Token)
这是默认和推荐的授权模式：
- 使用用户的飞书身份调用 API
- API 权限范围受限于用户本身的飞书权限
- 无需额外配置权限范围
优点：
- 用户能看到什么，机器人就能操作什么
- 无需在开发者后台配置权限范围
- 更安全，权限边界清晰
2. 应用身份授权 (Tenant Access Token)
使用应用身份调用 API：
- 需要在开发者后台配置权限范围
- 可以操作应用拥有权限的所有资源
适用场景：
- 需要操作用户无权访问的资源
- 后台自动化任务
首次授权流程
自动触发
当用户首次使用插件功能时，会自动触发授权流程：
- 用户发送消息给机器人
- 机器人发送授权卡片（包含二维码）
- 用户扫码并确认授权
- 授权成功，机器人获得用户身份
手动触发
用户也可以手动触发授权：
发送消息：授权 或 /feishu_auth
权限范围说明
用户身份权限
用户身份授权的权限范围完全受限于用户本人在飞书中的权限：
- 如果用户只能访问 A、B 文档，API 也只能访问 A、B
- 如果用户被移除某个文档的访问权限，API 同样会失败
这意味着：
- ✅ 你能看到的文档 → 机器人也能看到
- ❌ 你不能看的 → 机器人也看不到
应用权限
在飞书开放平台的应用权限管理页面，需要开通相应的 API 权限：
| 功能模块 | 必需权限 |
|---|---|
| 消息收发 | im:message:send_as, im:message:receive |
| 文档操作 | doc:readonly, doc:upload, doc:create |
| 多维表格 | bitable:readonly, bitable:create |
| 日历日程 | calendar:readonly, calendar:event:create |
| 任务管理 | task:readonly, task:create |
| 云盘操作 | drive:readonly, drive:upload |
撤销授权
用户可以随时撤销授权：
发送消息：撤销授权 或 /feishu_revoke
撤销后：
- 机器人无法再以该用户身份调用 API
- 需要重新授权才能继续使用
常见问题
Q: 授权后仍无法访问某些文档？
原因：用户身份权限受限于用户本身的飞书权限
解决：
- 检查用户是否有该文档的访问权限
- 如需更高权限，考虑使用应用身份授权
Q: Token 过期怎么办？
说明：用户身份授权的 token 会在约 2 小时后过期
解决：插件会自动使用 refresh_token 刷新，无需用户操作
Q: 多用户使用需要注意什么？
建议：
- 每个用户需要单独授权
- 不同用户的权限可能不同
- 可以通过配置实现多账号隔离